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NTRODUCTION 



Borland's Turbo Profiler is the missing link in your software 
development cycle. Once you have your code doing what you 
want. Turbo Profiler helps you do it faster and more efficiently. 

So what is a profiler? Profilers (also known as performance 
analyzers) are software tools that measure a program's 
performance by finding its bottlenecks: 

Q where your program spends its time 

a how many times a line executes 

D how many times a routine is called, and by which routines 

Q what files your program accesses most and for how long 

Profilers also monitor critical computer resources: 

a processor time 
m disk access 
Q keyboard input 

□ printer output 

□ interrupt activity 

By monitoring vital activities and providing detailed statistical 
reports on every part of your program's performance, Borland's 
Turbo Profiler enables you to fine-tune your programs. By 
opening up the inside of your program and exposing its most 
intricate operations — from execution times to statement coimts, 
from interrupt calls to file access activities — ^Turbo Profiler helps 
you polish your code and speed up your programs. 

Turbo Profiler surpasses other profilers on the market both in 
power and ease of use: 

□ Interactive profiling quickly reveals inefficient code in a 
program. 

□ Profiles any size program that runs under DOS. 



Introduction 



■ Handles programs written in Turbo Pascal, Turbo C++, Turbo 
C, and Turbo Assembler, as well as programs compUed with 
Microsoft C and MASM. 

■ Has an easy-to-use interface with multiple overlapping 
windows, mouse support, and context-sensitive help. 

■ Reports execution time and execution count for routines and 
individual lines of a program. 

■ Tracks complete call path histoiy for all routines. Analyzes 
frequency of calls with complete call stack tracing. 

■ Monitors DOS file activities from the Files window by fQe 
handle and time of open, close, read, or write. Event list logs 
number of bytes read or written. 

■ Supports selective interrupt monitoring. Monitors all video, 
keyboard, disk, and mouse interrupts, and custom interrupts. 
Provides a complete event Hst or frequency monitoring. List of 
common DOS calls by sjnnbolic name lets you quickly identify 
interrupts. 

■ Supports complete tracking of Turbo Pascal and Turbo C 
overlays. 

■ 386 virtual machine profiling uses no RAM — leaves all of your 
RAM available for your program. 

■ Allows remote profiling. 

■ Supports programs in C and assembler compatible with 
Codeview .EXE format files. 

■ ProfQes any program from any compiler if if s accompanied by 
standard Microsoft format .MAP files. 

By picking up where code optimizers leave off. Turbo Profiler 
directs you immediately to slow code, pointing out where to open 
up bottlenecks and when to rework algorithms. 



The difference 

between 

optimizing and 

profiling 



An optimizer makes your program run a little faster by replacing 
time-consuming instructions with less expensive ones. But 
optimizing can't fix inefficient code. 

The profiler helps you to detect the part of your code that is least 
efficient and helps point to algorithms which can be modified or 
rewritten. Studies show that the largest performance improve- 
ments in programs come from changing algorithms and data 
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structures, rather than from optimizing small segments of 
compiled code. Trying to find bottlenecks without a profiler is like 
trying to find bugs without a debugger; Turbo Profiler reduces 
both time and effort. 

Hardware and software requirements 

Turbo Profiler runs on the IBM PC family of computers, including 
XT, AT, the PS/2 series, and all true IBM compatibles. DOS 2.0 or 
higher is required and at least 384K of RAM. Turbo Profiler will 
run on any 80-column monitor. We recommend a hard disk, 
although it is possible to profile on a computer with two floppy 
disk drives. 

Turbo Profiler does not require an 80x87 math coprocessor. 

Installing Turbo Profiler 

To install Turbo Profiler on your system, run INSTALL.EXE, the 
easy-to-use installation program on your distribution disks. This 
program automatically copies files from the distribution disks to 
your hard disk. Just insert the Install disk in your A drive, type 
A: INSTALL, and press Enter. Then follow the instructions on the 
screen. 

The distribution disks are formatted for double-sided, double- 
density disk drives and can be read by IBM PCs and close 
compatibles. For a list of the files on your distribution disks, see 
the README file on the Installation disk. 

The README file 

n^ Take a look at the README file on the Install disk before you do 
anything else with Turbo Profiler. This file contains last-minute 
information that might not be in the manual. It also hsts every file 
on the distribution disks, with a brief description of what each 
one contains. 

To access the README file, insert the Installation disk in drive A, 
switch to drive A by typing A: and pressing Enter, then type readme 
and press Enter again. Once you are in README, use the T and i 
keys to scroll through the file. Press Esc to exit. 
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What's in this manual 



Introduction (this section) tells you what profilers are in general, 
summarizes Turbo ProfQer's features, and gets you ready to run 
Turbo Profiler on your system. 

Chapter 1 , A sample profiling session, is a tutorial that takes you 
through a typical (albeit simple) profiling session. This chapter 
starts with a 'let's see what's going on" profile, then takes you 
through interpreting the profile data coUected, modifying and 
refining the program based on insight gained from the profile, 
and running additional profiles to gauge the effect of each 
successive modification. 

Chiapter 2, Inside the profiler, uses analogy to explain how the 
profiler gathers execution-time and execution-count data while 
your program runs. 

Chapter 3, Profiling strategies, provides general guidelines, along 
with some tips, for conducting a fruitful profiling session. 

Chapter 4, The Turbo Profiler environment, explains in detail each 
menu item and dialog box option in the Turbo Profiler 
environment. 

Appendix A, Turbo Profilerls command-line options, lists each 
Turbo Profiler command-line option and explains what the option 
accomplishes. 

Appendix B, Customizing Turbo Profiler, explains how to use 
TFINST to change the configuration defaults of TPROF. 

Appendix C, Remote profiling, describes how to profile with two 
systems; you run your program on one and Turbo Profiler on the 
other. 

Appendix D, Virtual profiling on the 80386 processor, explains 
how to run the profiler in 80386 extended memory, leaving the 
full 640K of real memory for your program. 

Appendix E, Prompts and error messages, lists all prompts and 
error messages that can occur, with suggestions on how to 
respond to them. 
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A note on 

TGrminolOQy For convenience and brevity, we use son\e terms in this manual in 
slightly more generic ways than usual- These terms are module, 
routine, and argument. 

module A module in this manual refers to what is usually called a module 
in C and in assembler, but also refers to what is called a unit in 
Pascal. 

routine Similarly, a routine in this manual refers to both a C function and 
to what is known in Pascal as a subprogram (or routine), which 
encompasses /wMch'ons, procedures and object methods. In C, a 
function can return a value (like a Pascal function) or not (like a 
Pascal procedure). (When a C function doesn't return a value, it's 
caUed a void function.) We use routine in a generic way to refer to 
both C functions and Pascal functions and procedures. 

argument Finally, the term argument is used interchangeably with parameter 
in this manual. This apphes to references to command-line 
arguments used to invoke a program from DCDS, as weU as 
arguments passed to routines. 



How to contact Borland 



If, after reading this manual and using Turbo Profiler, you would 
like to contact Borland with comments, questions, or suggestions, 
we suggest the following procedures: 

m The best way is to log on to Borland's forum on CompuServe: 
Type GO BPROGB at the main CompuServe menu and follow the 
menus to Turbo Profiler. Leave your questions or comments 
there for the support staff to process. 

m If you prefer, write a letter detailing your problem and send it 
to 

Technical Support Department — ^Turbo Profiler 

Borland International 

P.O. Box 660001 

1800 Green Hills Drive 

Scotts Valley, CA 95066-0001 

□ You can also telephone our Technical Support department 
between 6 a.m. and 5 p.m. at (408) 438-5300. To help us handle 
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your problem as quickly as possible, have these items handy 
before you call: 

• product name (Turbo Profiler) and version number 

• product serial number 

• computer make and model number 

• operating system and version number 

• the contents of your CONFIG.SYS and AUTOEXEC.BAT files 

If you're not familiar with Borland's No-Nonsense License 
statement, now's the time to read the agreement included with 
this package and maU in your completed product registration 
card. 
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A sample profiling session 



We Ve based the examples in 

this chapter on Jon Bentley's 

"Programming Pearls' 

column (July 1987) In 

Communications ofthie 

ACM. 

All tt)e tutorial examples 

were run on a 286 machine 

with a Hercules video 

adapter. 



Profiling is one of the least-understood yet most useful and vital 
areas of good software development. Surveys indicate that only a 
smaU fraction of professional programmers actually use profilers 
to improve their code. Other studies show that, most of the time, 
even the best programmers guess wrong about where the bottle- 
necks are in their programs. 

What is the advantage to using this widely overlooked tool? For 
one, profiling your program can increase its overall performance. 
Second, profiling can augment your ability to produce efficient 
code. The bottom line is that profiling, Kke debugging, can be a 
cog in the wheel of the program development cycle. 

In this chapter we show you an example of profiling put to good 
use, and how — ^in the long run — profiling can save you hours of 
hunting for that expensive line of code. You use Turbo Profiler to 

D see where your program spends its time 

D create an annotated source listing and a profile statistics report 

B save profile statistics, then start up again with saved statistics 

B analyze profile statistics and source code in side-by-side 
windows 

The examples in this chapter are based on finding and printing all 
prime numbers between 1 and 1,000. Recall that a number is 
prime if it is divisible by only the integer 1 and itself; it must also 
be odd, since any even number is divisible by 2 and therefore is 
not prime. You can tell whether a particular number is prime by 
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checking to see if it is divisible by other, smaller primes, or by any 
integer larger than the first two primes, 2 and 3. 

The object of profiling the example programs is to speed up the 
process of finding and printing the prime numbers. As you work 
through the examples, you'll learn how to use Turbo Profiler to 
test the efficiency of each example's structure. 

The first program you'll look at is PRIMEO. Once you've profiled 
it and seen where to modify the code, all you need to do is load 
and profile PRIMEl. With the exception of PRIMEl, each of the 
programs covered in this chapter (PRIME2, PRIMES, PRIME4, 
PRIMES, and PRIME6) is a variation on its predecessor. 

Pascal users The PRIMEn.* programs are Turbo C programs. For Pascal 

programmers, we've also supplied Turbo Pascal versions of them 
on disk (PRIMEnPA.*) that you can run as you go through this 
chapter. To each discussion of the C program's profile results, 
we've added comments about what you'll see if you're running 
the Pascal programs instead. 

Make sure the files for aU the example programs (PRIMEn.C and 
PRIMEn.EXE or PRIMEnPA.PAS and PRIME«PA.EXE) are in 
your current directory. 

For each of the examples we've provided both the source code 
and the executable code; Turbo Profiler requires both to analyze a 
program. Each of the examples was compiled with fuU symbolic 
information, since the profiler also requires this information. 

cj^ To ensure that your programs contain full sjonbolic information, 
compile them with the appropriate compiler options turned on: 

■ Turbo C++: If you are compiling in the IDE, turn on Options I 
Full Menus, then open the Debugger dialog box (choose 
Options I Debugger), and set Source Debugging to Standalone. 
If you are compiling from the command line, use the -v 
command-line option. 

■ Turbo C: If you are compiling in the IDE, specify Standalone in 
the Debug I Source Debugging option before you compile your 
modules. If you are compiling from the command line, specify 
the -V command-line option. 

■ Turbo Pascal: If you are compiling in the IDE, set the Options I 
Debug Information and Debug I Stand- Alone Debugging 
options to On. If you are compiling from the command line, use 
the /V command-line option. 
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80x87 users 



a Turbo Assembler: Use the /zi command-line option, then link 
the program with TLINK, using the /v option. 

While TPROF works with numeric coprocessors, if your system 
has an 80x87 chip, you have to fool it temporarily into thinking 
the 80x87 is unavailable so you'll get results similar to the ones 
shown in this tutorial. (Otherwise, the statistics here won't even 
approach what you'll see on your screen.) Just set an environment 
variable at the DOS prompt with the command set 87=n before 
running the profiler. Of course, the statistics you get might still 
vary from what appears in the figures in this adapter; this occurs 
because of differences in individual systems (CPU speed, etc.). 



Profiling a program (PRIMEO) 



Loaving Turbo Profiler at ar)y 

time Is a simple, one-step 

procedure: just chioose File I 

Quit or press M-X. 

Pascal users 



You profile and improve a program in four steps: 

1. Set up the program before profiHng it. 

2. Collect data while the program runs. 

3. Analyze the collected data. 

4. Modify the program and recompile it. 

After modifying your program, repeat Steps 1 through 3 to see if 
the modifications have improved your program's performance. 

PRIMEO uses EucHd's method of testing for prime numbers, a 
straightforward integer test for a remainder after division. As 
each prime number is found, it is stored in the array primes, and 
each successive number is tested for "prime-ness" by being 
divided by each of the numbers already stored in primes. 

Load PRIMEO into Turbo Profiler by typing 

TPROF PRIMEO 

and pressing Enter. 

If you want to profile the Turbo Pascal version of PRIMEO.C, 
make sure PRIMEOPA.PAS and PRIMEOPA.EXE are in your 
current directory, and enter 

TPROF PRIMEOPA 

The profiler comes up with two windows open: the Module 
window (which displays PRIMEO's source code) and the 
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Figure 1.1 

Turbo Profiler with PRIMEO 

loaded 



Execution Profile window (which will display profile statistics 
after you run PRIMEO). 



=L!T=+ioduTe: PRII 



un statistics Srint iptions Iindow ielp 



: PRIKEO File: priroeO.c (modlned; 7= 
7* Copyright (c) 1990, Borland International */ 
/• Program for generating prine numbers using Euclid's method •/ 

int primes [1000]: 
Idefine HAXPRIHES 1000 

'► roainO 

int j; 

Int lastprime, curprirae; 



^l^[i]= 



-Execution Profile- 
Total time: sec 
h of total : 100% 
Runs: of 1 



Display: Time 
Filter: All 
Sort: Frequency 




For a more detailed 

description of the profiler's 

environment, see Ct)apter4. 



The Module and Execution Profile windows are concerned with 
Steps 1 and 3 in the profiling process. You use the Module 
window to determine what parts of the program to profile. Once 
you run a program, the Execution Profile window displays the 
information you need to analyze your program's behavior. 



Setting up the 
profile options 



Before you begin to profile your program, you must specify the 
areas you want to profile. An area is a location in your program 
where you want to collect statistics: An area can be a single line, a 
construct such as a loop, or an entire routine. For your first 
profile, you want more information than Turbo Profiler's default 
area settings provide. 

To analyze a small number of short routines (like prime and main 
in this program), you have to know how often each Hne executes 
and how much time each line takes. To get this information, you 
must mark every Hne in the program as an area. 

1. Press Alt-F10 to open the Module window local menu. 

2. Choose Add Areas from the local menu. This menu lists area 
boundaries for you to choose from. 
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3. Choose Every Line in Module. This sets area markers for all 
lines in the module, then returns the cursor to the Module 
window. 

Notice that all executable lines inside the module are now tagged 
with a marker symbol (=►). 



Collecting data 



Figure 1.2 
Program statistics, PRIMEO 



Now you're ready for the second step in the profiling process. 
Press F9 to run PRIMEO under Turbo Profiler. The program prints 
the prime numbers between 1 and 1,000 on the User screen. When 
the program finishes, look at the information in the Execution 
Profile window. These are your program statistics. 

Zoom the Execution Profile window: Press F5 or choose Zoom 
from the Window menu. The Execution Profile wmdow should 
now look like this: 



«|»ai'leWflietf«Eun»Etatistics»finintKiptionsWiindow»Ielpm^^^^ 



f=L"J=txecution hron ie= 
Total tiine: 6.6910 sec 
% of total : 99 h 
Runs: 1 of 1 



Display: Time 
Filter: All 
Sort: Frequency 



IREADY 



#PRIHE0#31«!«ffa8E6s;2655sseclils93% 



#PRIME0I17 
#PRIHE0#18 
#PRIME0#21 
IPRIKE0f28 
IPRIHE0#19 
#PRIHE0#24 
IPRIHE0I29 
fPRIHE0f25 
#PRIHE0#32 
#PRIHE0#33 
fPRIKEOfSO 
main 

?PRIHE0#35 
fPRIHEOI14 
#PRIME0#13 



0.3069 
0.0359 
0.0354 
0.0071 
0.0060 
0.0059 
0.0038 
0.0037 
0.0034 
0.0019 
0.0018 
0.0017 
0.0000 
0.0000 
0.0000 
0.0000 



secliis93%:iii| 


sec 


4% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


«:1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 


sec 


<1% 



Alt: FiassaiaEDFs 



iFqggfTrnFtaiOTBlFfiainTifiWFI nHTTglll.il J.IIWMIM 



The upper pane of the Execution Profile window displays the 
program's total execution time, along with information about the 
data in the lower pane. The lower pane has four entries on each 
Hne: 

□ an area name 

□ the number of seconds spent in that area 

□ the percentage of total execution time spent in that area 
a a magnitude bar proportional to the percentage 
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Pascal users 



This line 

*PRIME0f31 6.2655 sec 93% |= 



tells you that the thirty-first line of code in module PRIMEO 
executed for about 6.3 seconds — ^which was 93% of the total 
execution tinie for all marked areas. The magnitude bar 
automatically shows Line 3rs time full-scale (because Line 30 is 
the most time-consiiming of the marked areas). 

In PRIMEOPA, the corresponding line of code is line 42. 



Displaying 
statistics 



Display... 
Filter 



All ► 



Module 
Remove 



Figure 1.3 

The Display Options dialog 

box 



You can also display this program's collected data as execution 
counts. 

1. Press Alt-F10 to bring up the local menu for the Execution 
Profile window. 

2. Choose Display on the local menu. 

The Display Options dialog box lists five possible ways to 
display data in the Execution Profile window. 




■ Time shows the total time spent in each marked area. (This 
is the default.) 

■ Counts displays the number of times program control 
entered each area. 

■ Both shows time and counts data on the same screen. 

■ Per Call displays the average amount of time per call. 

■ Longest shows the longest time spent in each area. 

3. Choose Counts under Display in this dialog box. (Click Counts 
with the mouse, or use the arrow keys to move to it and press 
Enter, or press C, the hot key for this option.) 

4. Choose OK (or press Enter). 
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Figure 1.4 

Counts display in Execution 

Profiie window 



The Execution Profile window now displays PRIMEO's statistics as 
execution counts instead of execution times, as shown in this 
figure: 



i=W=Execution ProfTT e 

Total time: 6.4478 sec Display: Counts 

* of total: 99 % Filter: All 

Runs: 1 of 1 Sort: Frequency 



IPRIME0#I9 
IPRIHEOIZS 
#PRIHE0f21 
IPRIHEOfZe 
#PRIHE0I29 
IPRIHE0I24 
fPRIME0#31 
fPRIHEOI32 
#PRIHE0#33 
#PRIHE0#30 
main 

7PRIHE0I18 
#PRIHE0#17 
fPRIHE0#15 
IPRIHE0#14 
#PRIKE0#12 



15122 


;R?%r 


sW 


-w 


499 


2% 


499 


2% 


333 


1% 


333 


1% 


333 


1% 


166 


<1% 


166 


<1% 


166 


<1% 


166 


<1% 




<1% 




<1V 




<1% 




<1% 




<1% 




<1% 



IREADY 



TIT'''' iTr'''Tii''' 111 III I II ' ili"La 



Fiaiai3aF2ga3^F3a2HiFSEEfflF6fiBsaF9S2!nnFioaEii!E 



'g' .'>i:S'v;' 



This display of PRIMEO's statistics shows that line 22 is the most 
often called line in PRIMEO. (It's line 31 in PRIMEOPA.) 

You can also see counts and times together. Bring up the Display 
Options dialog box again (either press Alt-F10 and choose Display, 
or press Cti'l-D). 

Choose Both imder Display, then choose OK or press Enter. (To 
choose Both, either click it, or press i to get to it, then press Enter, 
or press B, the hot key for this option.) 

Now the Execution Profile window looks Hke this: 



Chapter L A sample profiling session 



13 



Figure 1.5 

Tim© and Counts in tin© 

Execution Profiie window 



■^F[iFMv ffgM l fflill s nht8H*rMi l 
ir=["I=Execution Profil e 



=[iT=€xecution Pr 
Total tine: 6.6910 sec 
% of total : 99 % 
Runs: 1 of 1 



Display: Tine and counts 
Finer: '" 



READY 



fPRIHEOfZZ 
fPRIHE0#17 
fPRIKEOflS 
#PRIME0»21 
fPRIHEOI28 
#PRIKE0#19 
»PRIME0»24 
#PRIHE0I29 



Sort! 



An 

Frequency 



6.2655 sec 

15122 

0.3069 sec 

1 

0.0359 sec 

1 

0.0354 sec 

499 
0.0071 sec 

499 
0.0060 sec 

500 
0.0059 sec 

333 
0.0038 sec 

333 



93% 
82% 

4% 
<1% 
<1% 
<1% 
<1% 

2% 
<1% 

2% 
<1% 

2% 
<1% 

1% 
<1% 

1% 



Alt: FlBra«!aniF2BMI»ITmWCTF3HiiBtaFSHIIT!aF6HinBBlFlC 



When the Execution Profile window displays time and counts 
together, the first entry for each area is execution counts, and the 
second is execution time. Figure 1.5 shows that the area 
PRIME0#22 (line 22 in PRIMEO) was called 15,122 times 
(execution counts) and took up 0.31 seconds of total execution 
time. 



Printing modules and statistics 



In this section, you print two things: 

1. a profile source listing of the code thaf s in the Module 
window, with time and counts data attached to each marked 
area 

2. the profile statistics displayed in the Execution Profile window 

Time and counts 

profil© listing Before you print a time-and-counts profile listing to a file, you 
must set the appropriate printing options. 



1. Choose Print I Options. 

2. In the Printing Options dialog box, choose the File radio 
button (press Tab until the radio buttons become active, then 
press i to turn the setting to File). 
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The times in your file probably 

vary from these somewhat 

because each computer is a 

little different. 



3. Tab to the Destination File input box and type 

PRIMEOSC.LST 

4. Choose ASCII to use the standard ASCII character set (rather 
than the IBM extended character set). 

5. Choose OK (or press Enter). 

The cursor returns to the active Execution Profile window. 

Now, to print the listing file, choose Print I Module. In the Pick a 
Module dialog box, press i to highlight the module name 
PRIMEO, then press Enter (or choose OK). 

You can shell out to DOS to see the file PRIMEOSC.LST, which 
prints to the current directory. Choose File I DOS shell and, at the 
DOS prompt, type 

TYPE PRIMEOSC.LST 

This is what you see if you're profiling the Turbo C program, 
PRIMEO: 

Turbo Profiler Version 1.0 Tue Feb 27 15:16:47 1990 
Program: D:\TPROF\PRIME0.EXE File primeO.c 
Time Counts 



method */ 



/* Copyright (c) 1990, Borland International */ 

/* Program for generating prime numbers using Euclid's 



int primes [1000]; 
Idefine MAXPRIMES 1000 



0.0000 1 



raainO 



0.0000 1 
0.0000 1 
0.0000 1 
0.0000 1 

0.0359 1 
0.0354 1 
0.0059 500 

0.0071 499 
0.3069 15122 



int j; 

int lastprime, curprime; 

primes [0] = 2 
primes [1] = 3 
lastprime = 1 
curprime = 3 

printf ("prime %d = %d\n", 0, primes[0]); 
printf ("prime %d = %d\n", 1, primes[l]); 
while (curprime < MAXPRIMES) 
{ 

for(j = 0; j <= lastprime; j++) 
if ((curprime % primes [j]) == 0) 
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0.0038 333 


curprime += 2; 


0.0034 333 


break; 
1 


0.0060 499 


) 
if(j <= lastprime) 


0.0037 333 


continue; 


0.0017 166 


lastprime++; 


6.2655 166 


printf ("prime %d = %d\n", lastprime, curprime); 


0.0019 166 


primes [lastprime] = curprime; 


0.0018 166 


curprime += 2; 



0.0000 1 



This profile source listing is useful because it's a permanent record 
that shows, for each area in your program, the execution time and 
execution counts. 

Now type exit at the DOS prompt and press Enter to return to 
Turbo Profiler. 



Profile statistics 



report You can also print a replica of the open Execution Profile 
window's contents to your printer or to a disk file. 

1. Choose Print I Options again. 

2. Choose the Printer radio button. 

3. Choose Graphics to include IBM semi-graphic characters in 
the printed report. (If your printer does not support IBM high 
ASCII characters, like [f and ^, skip this step and proceed to 
Step 4.) 

4. Press Enter (or choose OK). 

5. Choose Print I Statistics. 

The resulting printout, hke the profile source listing, is a 
permanent record of your progress as you go through the steps of 
profiling, modifying, recompiling, and reprofiling in your quest 
for the sleekest and most efficient code possible (and practical) for 
your program. 
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Saving and restoring statistics 



Before you go on, here's how to save PRIMEO's profile statistics to 
a file, so you can quit Turbo Profiler at any time without losing 
the data. We also show you how to restore those statistics the next 
time you start the profiler. 

Choose Statistics I Save to save your program's profile statistics to 
a .TFS (Turbo Profiler Statistics) file. Because PRIMEO is in the 
Module window, the FUe Name input box lists PRIMEO.TFS as the 
default. Choose OK to create this file. 

All the statistical data from the current profile run of PRIMEO is 
now saved in the file PRIMEO.TFS in the current directory, so you 
can quit the profiler at any time without losing any of that 
information. Open PRIMEO in the profiler, and choose Statistics I 
Restore. As before, the FUe Name input box lists PRIMEO.TFS as 
the default. Press Enter to go to the Files list box, highlight 
PRIMEO.TFS, and choose OK to recover the data from this file. 



Analyzing the statistics 



We cover modifications to 
tine prinff statement In 
program PRIMES and— for 
you Pascal users- 
Introduction of the uses CRT 
statement In PRIME5PA. 



In this section you learn how to analyze the statistics in the 
Execution Profile window, so you can use what they reveal to 
streamline your program. 

First, though, take another look at the time and count statistics in 
the Execution Profile window. Unzoom the Execution Profile 
window (choose Zoom from the Window menu or press F5) and 
look at the statistics for lines 22 and 31 (the if and printf 
statements). 

Pascal users in PRIMEOPA ifs line 31 (if) and hne 42 (Writeln). 

A time and count profile like this teUs a lot about a program. For 
instance, you can see that line 22 in PRIMEO executes far more 
frequently than any other statement. It makes sense that line 22 
executes 15,122 times, since it tests every number between 4 and 
1,000 against every number in the array primes, until there is even 
division or the array is exhausted. That means a lot of numbers to 
be tested. You can also see that line 31, the printf statement, 
accounts for most of the program total execution time. 
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Viewing both 

source code and 

statistics 



The data in the Execution Profile window shows that the test in 
line 22 is doing more work than it should. But you can't really get 
the entire picture until you look at execution time and coxmt data 
and source code together. 

What you need to do is compare time and count data in the 
Execution Profile window and the corresponding source code in 
the Module window. 

Here's one way to display source code and profile statistics 
simultaneously: 

1. Resize and move the Execution Profile window so it occupies 
the right half of your screen: Choose Window I Size/Move, or 
press Ctrl-F5. 

2. Follow the directions on the status line to 

a. Resize the window to full-screen height and half-screen 
width. 

b. Move the resized window to the right. 

When you've done steps a and b, press Enter. 

3. Activate the Module window by pressing F6, then resize and 
move it so it occupies the left half of the screen. 

4. Go back to the Execution Profile window (press F6 again). 

To resize a window with the mouse, drag the Resize box in the 
lower right comer; to move the window, drag the title bar or any 
double-line left or top border character (|| or =). 

There is an automatic link between the Execution Profile window 
and the Module window, so that when you move through the 
source code, the execution profile display tracks the cursor's 
current Hne position. To see this tracking feature in action, 

1. Activate the Execution Profile window (press F6), and move 
the highlight bar to the first line (statistics for line 31 of 
PRIMEO, hne 42 of PRIMEOPA). 

2. open the local menu (press Alt-FlO) and choose Module (or just 
press Ctrl-M). 

The profiler positions the cursor on line 31 in the Module 
window. 
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3. Use the arrow keys to move through the source code to line 22 
(Hne 31 in PRIMEOPA). 

This line is the second largest time consumer in PRIMEO. The 
top two statistics lines in the Execution Profile window now 
display the profile data for this If statement. 

4. Move the cursor in the Module window to line 21 (hne 29 of 
PRIMEOPA) and note how the display in the Execution Profile 
window tracks with it. The top lines in the Execution Profile 
window are now the profQe statistics for line 21. 

5. Move the cursor to Hne 30 (line 42 of PRIMEOPA) and note the 
display in the Execution Profile window. 

Having the two windows synchronized this way makes it easy to 
find the greatest resource hogs in your program. Once you get a 
better feel for interpreting the data onscreen, you won't need to 
rely as much on profile listings like the one on page 16. 

Saving the window This is a good time to save your customized version of Turbo 

configuration Profiler. If you don't save your customized window arrangement, 
the windows will revert to their default size and placement the 
next time you load a program into the profiler. 

1. Choose Options I Save Options. This brings up the Save 
Configuration dialog box. 

2. By default, the Options check box is already checked. This 
records settings (such as the Execution ProfQe window's 
display options) in the configuration file. 

3. In the Save Configuration dialog box, tab to Layout and press 
Spacebar. This causes your side-by-side window layout to be 
saved in the configuration file. 

4. By default, the configuration file to be saved is TFCO^JFIG.TF, 
listed in the Save To input box. Choose OK, or press Enter, to 
save your options to this fQe in the current directory. 

Wherever you start up Turbo Profiler, it looks for TFCONFIG.TF, 
the default configuration file. When the profiler finds that file, the 
options and layout you've set will come up automatically. 
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Measuring an 
area's efficiency 



The ratio of execution time to execution counts is a good measure 
of a line's or routine's overall efficiency. To see this ratio for the 
areas in PRIMEO, change the display option in the Execution 
Profile window. Here's how: 

1. From the Execution ProfQe window's local menu (press Alt-FlO, 
choose Display. 

2. Under Display in the dialog box, choose Per Call. 

3. Choose OK (or press Enter). 

Now you can see that line 22 is much more efficient than line 31 
(in PRIMEOPA, lines 30 and 41). It uses up a lot of execution time 
because it executes so many times, but each individual call 
averages much less than a mOlisecond. Line 31, on the other hand, 
averages nearly 38 milliseconds per call (in PRIMEOPA, line 42 
averages 28 milliseconds). 

c!^ The output from the profiler points the way to improving the 

execution time of PRIMEO and making it structurally simple. The 
task of improving the program can be divided into two strategies: 

1. Reduce the amount of time spent in input/output. 

2. Rewrite the looping structure to be more streamlined and 
efficient. 

The input/output problem can be partially resolved by reducing 
the printf statement from its present form 

printf ("prime f%d = %d\n", lastprime, curprime) 

to simply 

printf ("%d\n", curprime) . 

Pascal users You can change the VJriteln statement to 

Writeln(CurPrime) ; 

Just this simple modification results in a considerable savings in 
the execution time. However, you can't reduce the number of 
times you call the output statement; for the given problem, there 
will always be 168 primes to print out. And apart from this minor 
improvement, there is not a great deal you can do to speed up the 
execution of PRIMEO. Its algorithm, which requires saving all the 



20 



Turbo Profiler User's Guide 



previous results in an array and then using them to divide, is 
thorough but virtually impossible to streamline. (It is also not 
very memory-efficient, because the array requires an allocation of 
memory equal to the number of primes being tested. Eventually 
this imposes a limit on the number of primes that could be tested 
without running out of memory.) 

Fortunately, there is a better way to test for prime nimibers: You 
can change the algorithm itself. Thafs what happens in the next 
example program, PRIME 1. 



A modularized primes test (PRIIVlEl) 



Pascal users: Load PRIMEIPA. You're finished with PRIMEO now, so load PRIMEl (Pascal users: 

PRIME 1 PA), the next version of the prime number program, into 
the Module window and look at the code. 

1. Choose File I Open. 

2. By default, the File Name input box is activated and contains 
the file-name mask *.EXE. Press Enter. 

3. In the Files list box, use the T and i keys to highlight 
PRIME1.EXE (PRIME1PA.EXE). 

4. Press Enter. Turbo Profiler loads PRIMEl (PRIMEIPA) into the 
Module window. 

5. Zoom the Module window (press F5). Note the added prime 
iPrime) routine on line 4. 

You can see right away that two major changes have occurred: 

B The array primes is gone. This program does not test by 
dividing each number by all smaller primes; it simply uses a 
loop to divide by all the odd numbers up to but not including 
the suspected prime. Initially this algorithm results in more 
iterations, but we wiU see that it eventually can be refined into a 
more streamlined and readable program. 

m The prime number test itself has been placed in a separate 
routine that is caUed from the main program. 

Set your areas (choose Add Areas I Every Line in Module from the 
Module window local menu), press Enter, then run (F9) PRIMEl in 
Turbo Profiler and look at the statistics. Then choose Display from 
the Execution Profile window local menu to open the Display 
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Figure 1.6 

Time and count statistics, 

PRIMEl 



Options dialog box and turn on the Both radio button. Press Enter, 
then zoom the Execution Profile window {F5). 



1 


1 ^i iile ijiew Cun statistics Qrint options Window lelp INJJiTI 


f=L'J execution rroTi ic =i 'L*J°i 


Total tine: 4.5675 sec Display: Time and counts 
% of total: 99 % Filter: All 


Runs: 1 of 1 Sort: Frequency 


1 


1 #PRIHE1#21 168 <1% 


^\ 


3.1294 sec 68% 
IPRIHE1#9 78022 93% 

1.3470 sec 29% 
#PRIME1#20 999 1% 









0.0299 sec <1% 


IPRIHElfS 999 1% 




0.0142 sec <1% 




fPRIHEl#12 999 1% 




0.0126 sec <1% 




jjrirae 999 1% 




0.0115 sec <1% 




IPRIHElflO 831 <1% 




0.0098 sec <1% 




IPRIMElIll 168 <1% 




0.0019 sec <1% 


B 


IPRIHE1#19 1 <1% 


M 











You can see that the execution time has improved somewhat (this 
is due in part to the fact that PRIMEl prints out less information 
than PRIMEO). The main bottleneck is still the printf statement 
(now line 21). (In PRIMEIPA ifs the Writeln statement, hne 24.) 

Notice in particular that the test for prime numbers (line 9 in 
PRIMEO, line 12 in PRIMEOPA) now executes 78,022 times instead 
of 15,122. This looks impressive at first, but notice that it only 
increases execution time for this line by about 1 second; we have 
already seen that this statement is very time-efficient. 

One obvious way to improve efficiency, now that we have 
isolated the test loop in a separate routine, is to cut down on the 
number of calls to the routine. There are ways of limiting the 
number of integers that have to be passed to the routine for 
testing; the more you can eliminate at the main program level, the 
fewer calls you have to make and the faster your program 
executes. That is the strategy we employ in the next several 
sample programs. 



Modifying tine program and reprofiling 

Bentley points out that instead of testing for all factors between 1 
and n in the modulus statement, you can set the upper limit of the 
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test to the square root of the number you're testing. That's what 
we've done in program PRIME2 (PRIME2PA). 



Loading another 
program (PRIME2) 



Go ahead and load PRIME2, the next version of the sample 
program, into the Module window. In program PRIME2, we've 
added a root (Root) routine that calls a square root library routine 
and returns an integer result. 

Pascal users Load PRIME2PA into the Module window. 

You need to set areas for all Knes in the module, so bring up the 
local menu and choose Add Areas I Every Line in Module, then 
press Enter. 

Press F9 to start the profile. Once again, you'll see the primes 
between 1 and 1,000 print to the User screen. 

When the program finishes running, open the Display Options 
dialog box (choose Display from the Execution Profile local menu) 
and set Display to Both. Press OK. Despite decreasing the number 
of calls to line 15 (from 78,022 to 5,288) and reducing the time 
spent in the same statement, there's still a substantial increase in 
overall execution time. 

The problem with PRIME2 (and PRIME2PA) is the expense of the 
new root routine. Line 7 inside the routine executes 5,456 times 
and consumes almost 5 seconds. At approximately 1 miUisecond 
per call, you can't afford too many passes through this routine. (In 
PRIME2PA ifs line 9.) 

When the Execution Profile window shows both time and count 
information, certain patterns are worth looking for. In inefficient 
routines, the second line (time data) is much longer than the first 
line (count data), which means the ratio of time to counts is high. 
This is the case for line 27, the printf statement (in the Pascal 
program, it's line 28). 

When the routine's timercount ratio is high, the best thing to do is 
substitute another routine. 

However, the return statement in the root routine (line 7), 
presents a different problem. It accounts for the largest number of 
calls and the largest amount of time. Two other lines (line 5 and 
line 8) have 5,456 calls, but the histogram bar for each of these 
cases shows small execution times. This is good: It means the 
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Reducing calls to 
a routine 
(PRIMES) 



statements are fast. So the biggest problem right now is the 
number of calls made to the root routine. 



The problem now is to reduce the number of calls to the root 
routine. Load PRIMES into the Module window, then zoom the 
Module window and take a look at the source code. 



Pascal users Load PRIME3PA into the Module window. 

In PRIMES, the only routine modified is prime. We've added a 
new integer variable, limit, and set limit equal to root(n) before 
entering the for loop. The test in the for loop is based on limit. 

Pascal users in PRIME3PA, we've added the integer variable Limit and set it 
equal to the root of n before entering the /or loop. The test in the 
for loop is based on Limit. 

In the Module window local menu, set areas to Every Line in 
Module. When you profile the program this time (choose Run I 
Run or press F9), the program runs quite a bit faster. PRIMES 
shows an almost 50% decrease in total execution time. 

The printf routine is now the major resource consumer, eating up 
over half the execution time. By reducing the number of calls to 
the square root routine in root (from 5,456 to 999), we've 
decreased computational time substantially. 



Still more 

efficiency 

(PRIME4) 



There are still more ways to increase the efficiency of the prime 
routine. Load PRIME4 into the Module window now, then 
examine lines 8 through 17 of the source code. 



Pascal users Load PRIME4PA and examine lines 1 1 through S2. 



/****** pRiME4,c ******/ 

if (n % 2 == 0) 
return (n==2) ; 

if (n % 3 == 0) 
return (n==3) ; 



{****** PRIME4PA.PAS ******} 

if (N MOD 2 = 0) than 
begin 

Prime := N = 2; 

exit; 
end; 

if (n MOD 3 = 0) then 
begin 

Prime := N = 3; 

exit; 
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Figure 1.7 

Time and count statistics. 

PRil\^E4 



if (n % 5 == 0) 
return (n~5) ; 



for (i=7; i*i <= n; i+=2) 
if (n % i == 0) 



return 0; 



return 1; 



end; 

if (N mod 5 = 0) than 
begin 

Prime := N = 5; 

exit; 
end; 
for I := 7 to N-1 do 

if (N mod I = 0) then 

begin 
Prime := False; 
exit; 

end; 
Prime := True; 



There are a number of improvements here. 

D The three if statements in the prime routine weed out factors 
that are multiples of 2, 3, and 5, respectively. If you can't throw 
out a number n based on one of these tests, you must test the 
remaining numbers, up to the root of n. You can start at the 
value 7 — the if statements have eliminated all possibilities 
below this number. 

D The for loop now increments by two on each iteration, because 
there's no point in testing even numbers. 

o The test i *i<=n has replaced the more expensive test 
involving the root routine. 

The net result is that we've shaved more than one second off the 
execution time. The count data in Figure 1.7 shows that printf now 
consumes 96% of run time. 



[r=[iJ=£xecution Profl 1 
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Reducing I/O 
time (PRIIVIE5) 



Pascal users load PRIME5PA 



Pascal users 



This change in the amount of time consumed by printf shows that 
the program is now I/O bound, rather than computationally 
bound. Perhaps thafs acceptable. But just for fun lefs try to 
squeeze a little more blood out of the I/O turnip. 

Load PRIMES into the Module window and look at line 28 (line 3 
in the Pascal version). 

Turbo C has a fast version of printf called cprlntf, which is 
PRIMES's only statement change from program PRIME4. cprintf 
handles newlines differently than printf does; in cprintf, an 
explicit carriage-retum/linefeed pair, \r\n, replaces the single 
newline character of printf. 

Turbo Pascal also has a fast version of VJriteln in the Crt unit. We 
tell PRIME5PA to use this fast version by including the uses Crt 
statement at the beginning of the program. This is the only change 
to PRIME5PA. 

Call up the Module window's local menu and set areas for every 
line in PRIMES's source module. Run PRIMES, then examine the 
profile count data for line 28 in PRIMES (or line 3 in PRIMESPA). 

The faster print routine saves almost a second in 168 calls. 



Eliminating CR/LF 
pairs (PRIME6) 



Here's one last change. Instead of printing a carriage-retum/line- 
feed pair after each prime number, try printing just a space. This 
is the only change made in program PRIME6. 

Load PRIME6 (Pascal users load PRIME6PA), set areas for every 
line, then run it. 

Surprise! Eliminating the carriage return /linefeed pair cuts 
execution time by a factor of almost 7. Apparently, printing new 
lines is expensive. The distribution of profiles is fairly even for 
execution times and counts (Figure 1.8). We'd be hard pressed to 
squeeze more out of this program without substantially changing 
the algorithm. 
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Figure 1.8 

PRIME6's execution times and 

counts 
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Where to now? 



We've taken you through the basics of profiling in this tutorial. By 
now, you should be familiar with using Turbo Profiler: loading 
and profiling programs, printing the contents of various win- 
dows, saving and restoring profile statistics, and rearranging the 
windows so you can analyze the statistics. 

Go ahead and quit the profiler now (choose File I Quit, or press 
Alt-X). 

For more information about Turbo Profiler's environment, as well 
as details about parts of the profiler not mentioned here, refer to 
Chapter 4, the complete Turbo Profiler environment reference. 

If you want more challenges than we've given in this tutorial, try 
these: 

□ Profile for primes less than 

o 2,500 
o 5,000 
o 7,500 
• 10,000 

o Set the profile mode (choose Statistics I Profiling Options to 
bring up the Profiling Options dialog box) to Passive analysis. 
What does this do to profiler overhead? What kinds of 



Chapter h A sample profiling session 



27 



information do you lose in passive analysis? (See Chapter 3 for 
information on passive profiling.) 

■ Find out what kind of performance improvement you get by 
implementing the Sieve of Eratosthenes to compute primes up 
to 10,000. 

■ Compare the cost of printing new lines with calls to position the 
cursor. 

There are a number of articles on the subject of profiling, but not 
many books. Jon Bentle)/s book, Writing Efficient Programs, 
provides a summary of rules for designing efficient code, suggests 
a comprehensive methodology for profiling, and contains an 
extensive bibliography. 
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Inside the profiler 



If you want to tise Turbo Profiler to your best advantage, you 
need to understand its inner workings. Knowing what the profiler 
does when it encounters an area marker or what happens each 
time the profiler interrupts program execution allows you to fine 
tune your techniques for specifying the type of information to 
collect and for interpreting the resulting reports. 

Consider the source code in PTOLL and PTOLLPAS: 



/* ****** PTOLL. C ***** */ 

finclude <stdlo.h> 
finclude <dos.h> 



void maiiiO 
I 

printf ("Entering main\n"); 

route66() ; 

printf ("Back in main\n") ; 

delay(lOOO); 

highvaySOO; 

printf ("Back in main\n") ; 

delay(lOOO); 

printf ("Leaving mainVnXn"), 



routQ66() 



{****** PTOLLPAS. PAS ******} 
Uses Crt; 

procedure Route66; 
begin 

Writeln( 'Entering Route 66' ); 
Delay (2000); 

Writeln( 'Leaving Route 66' ) ; 
end; 



procedure HighwaySO; 
begin 

Writeln( 'Entering Highway 80' ); 
Delay (2000); 

Writeln( 'Leaving Highway 80' ); 
end; 



printf ("Entering Route 66\n") ; 

delay (2000); begin 
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Figure 2.1 
Execution time and count 
compartments for PTOLL/ 

PTOLLPAS 



printf ("Leaving Route 66\n"); 



blghwaySOO 



printf ("Entering Highway 80\n") 

delay (2000) ; 

printf ("Leaving Highway 80\n"); 



Writeln( 'Entering main' 
Route66; 

Writein( 'back in main' ) 
Delay (1000); 
HighwaySO; 

Writeln( 'baclc in main' 1 
Delay (100); 

Writeln( 'Leaving main' ] 
and. 



); 



Setting the areas to All Routines in Module effectively sets up 
four time-collection compartments and four count-collection 
compartments. 



Execution 
Time 



Total 
malnO 
route66() 
hlghwaySOO 



Execution 
Counts 

□ 



Phantom tollbooths 



In this section, you follow program execution and see what 
happens as it passes each area marker. Think of this process as 
going through a series of toll booths. When you pass a toll booth, 
you're on a section of road associated with that toll booth until 
you come to another toll booth. 

You're in free space before you pass the first toU booth and after 
you leave the last toll booth. Each toll booth knows how long you 
spend on its road; it also keeps track of how many times you pass 
by. The only weird thing about this highway is that you can only 
go one direction down the road: Loops and jumps are like airlifts 
that take you back to some previous position on the road. As you 
move down the highway in program PTOLL, think of each area as 
a stretch of highway with an imaginary toll booth at each end. 



Here's how time and count collection works for a typical C or 
Pascal program. 

Before you enter the main program block, C startup code is 
executed. This is no man's land. Any timer ticks encountered here 
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are thrown away, unless you have explicitly set an area in the 
startup code. 

As soon as you pass the area marker (toll booth) at main, the 
count associated with main increments by 1. Any timer tick that 
occurs between the time you enter main and the time when 
route66 is caUed goes into main's timer compartment. 

Next, main calls route66 and you enter a new stretch of highway. 
The moment execution passes through the area marker (toU 
booth) at route66, several things happen: 

□ The current area is set to route66. 

D The compartment for the caller (main, in this case) goes on a 
stack. 

□ The count-collection compartment associated with route66 
increments by 1. 

Any timer tick that occurs between now and the time you return 
from route66 automatically increments route66's time-collection 
compartment. The global program time-collector also continues to 
increment with each timer tick. 

As soon as execution passes through a return point for route66, 
the profiler pops the caller's compartment from a stack. The 
caller's count compartment is not incremented on a return. 
However, any timer ticks that occur between now and the call to 
tiighwaySO are added to the time-collection compartment for main 
as well as to the program's global compartment. To verify this, try 
turning off route66's area marker and comparing the result with a 
profile for which that area marker was set. You should see 
essentially the same total execution time. However, main's 
execution time should increase by the amount of time it formerly 
took to execute route66. 



Determining tine 
overhead of 
routine coiis 



You might want to measure the time consumed by calling a 
routine (for example, route66) and ignore the time spent inside the 
routine. The easiest way to get there from here is to disable 
collection of information at the entry point for route66, and then 
to reenable collection upon return from route66.(You can also get 
this kind of information using passive analysis, which we discuss in 
Chapter 3). For now, position the cursor on the first line of 
route66, then choose Operation from the Module window local 
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menu to open the Area Options dialog box. Set Operation to 
Disable. Press Enter. 

When you disable collection on entry to route66, returning from it 
doesn't automatically reenable collection. You must set an area 
marker at the closing brace for route66, and set the area operation 
for that area marker to Enable again (in the Area Operations 
dialog box). 



Who pays for 

loops? The toll booth analogy helps explain why passing through an area 
marker and jumping back to an address that precedes that marker 
(using a loop or a goto statement) doesn't change the current area. 
Even though you are lexically outside the scope of the marker, 
you haven't passed through any new markers. Any timer ticks 
that occur will still be associated with the most recently tripped 
marker. 



/* ****** PLOST.C ****** */ 

finclude <stdio.h> 
tinclude <dos.h> 
lo8t_in__town ( ) ; 

=>vold mainO 



=> 



printf( "Entering main\n"); 

lost_ia_towa(); 

delay (1000) ; 

prlntf ("Leaving main\n\n") , 

delay (1000); 



=>lo8t in townO 



=> 



=> 



int i; 

printf ("Looking for highway... \n") ; 

delay (100); 

for (i=0; i<10; i++) => 

{ 

printf ("Ask for directions\n") ; 

printf ("Wrong turn\n\n"); 

delay (1000); 
} 
printf ("On the road again\n"); 



(****** PLOSTPAS.PAS ******} 
uses Crt; 

procedure Lost_in_town; 
var 

I : Integer; 
begin 
Writeln( 'Looking for highway 
Delay (100); 
for I := to 9 do 
begin 
Writeln( 'Ask for direction 
Writeln( 'Wrong turn' ); 
Writeln; 
Delay (1000); 
end; 

Writeln ( 'on the road again' 
end; 

begin 

Writeln ( 'Entering Main' ); 
Lost_in_town; 
Delay (1000); 

Writeln ( 'Leaving main' ); 
Writeln; 
Delay (1000); 
end. 
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In program plost, we've complicated the routine lost_ln_town by- 
using a compound statement inside a loop. Assume that three 
markers have been set: one for main, one for lostJn_town, and a 
line marker for the statement that prints Wrong turn. 

Things get tricky when you get into lost_in_town. When you first 
enter the routine, IostJn_town becomes the current area. The 
time associated with printing Looking for highway is associated 
with this marker. 

Time for executing the loop statement is still associated with the 
routine marker, and the first time you "Ask for directions/' the 
time is associated with the routine marker. However, once you 
trip the line marker for "Wrong turn," the remainder of the time 
spent in the routine is associated with that line marker. 

Just because you pass into an area that was previously associated 
with another marker doesn't mean the current area changes. The 
current area only changes when you trip an area marker. This can 
produce unexpected results. 

For instance, if you set the three markers for program plost as 
we've already described (one each for the main program blocic, 
iost_in_town, and the Wrong Turn statement), approximately 84% 
of program time will be associated with printing "Wrong turn," 
while only 1% of execution time will be associated with 
lost_in_town. This is because nine out of ten calls to "Ask for 
directions," plus all calls to the subsequent delay statement, are 
associated with the Wrong Turn marker. 

If you toggle off the area marker for "Wrong turn/' 84% of the 
remaining execution time will be logged to the routine 
iost_in_town. 

Consider the following code: 

main 

{ 

while (IkbhitO ) 
( 

fund ( ) ; 

statementl; 
statement2; 
func2(); 
) 
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funclO 

{ 

} 

£unc2() 

{ 

) 

Assume that areas are set for all routines in the module. The 
routines main, fund, and func2 each mark the beginning of an 
area, and the interrupt timer is ticking away at 100 times a second. 
(Pretend that 1/100 second is a long time, so you can see what's 
going on.) 

You enter main, which trips main's area marker. When this 
happens. Turbo Profiler internally encounters a breakpoint. This 
encounter sets a variable indicating that, until you trip another 
breakpoint, main is the current area. This encounter also 
increments a variable associated with execution counts for main 
byl. 

The scope of these areas is dynamic rather than lexical. That is, 
main is the current area until fund is called. As soon as you enter 
fund, you're in a new area until you encounter another function 
caU or until you return from fund . This means that the profiler 
puts the caller (main, in this case) on a stack. 

When you exit from fund, you trip a return marker that the 
profiler set up when it entered fund . The routine main becomes 
the current area again. Any timer ticks that occur while the 
program is executing statementl or statement! will update the 
timer for the area associated with main. 

Two things are going on here: 

1. Every time you encounter an area, the profiler calls an internal 
routine that adjusts variables and updates a routine call stack. 
Two variables are associated with each area: execution counts 
and execution time. Each time you enter an area, the execution 
count associated with that area increments. 

2. Every time a timer tick occurs, the profiler calls another 
internal routine that checks to see what area is current, then 
increments the timer variable associated with that area by the 
appropriate amount of time. 
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Something to keep in mind 
about return points. 



When the program terminates. Turbo Profiler converts the counts 
variable for each area to an actual time (based on the total number 
of timer ticks that occurred for the entire program). 

When you disable collection on entry to routine fund , returning 
from fund does not automatically reenable collection. You must 
explicitly reenable collection at fund's return point. 

What do you do about multiple return statements? The answer is 
related to the imphcit return points at the end of routines. 

Even though you might have several explicit return points in your 
program. Turbo C actually turns all returns into jumps to a single 
exit point at the end of the routine. The line that receives the area 
marking for a return statement is the line associated with the 
closing brace for the routine. This is the actual assembly language 
return statement to which all other return statements in the 
routine are vectored. 

To disable collection for a routine, set an area marker with a 
disable operation at the first line of the function and an enable on 
the line after the call to the function. 

If you want to throw out the time spent in fund but continue 
collection upon return from fund, you must set an area marker at 
fund's return statement. If no explicit return statement exists, 
mark the closing curly brace associated with the end of the 
routine. 



Logging callers 



An active routine is a routine currently on the profiler's routine 
call stack. In active analysis, (that is, with the profiler collecting 
call histories and other data not related to times) Turbo Profiler 
maintains its own routine call stack. This stack is similar to the 
stack found in any DOS program. However, the profiler's stack is 
separate from the user's program stack and is used strictly to 
retain information about routine calls for which a return 
statement has not yet been executed. 



In order to maintain an active routine stack. Turbo Profiler 
recognizes two types of area markers: 

Q Routine-entry area markers (routine markers) 
D Normal area markers (label markers) 
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When the profiler encounters a routine-entry area marker, it 
pushes the currently active routine (the last encountered routine- 
entry marker) onto its active routine stack. The newly 
encountered routine marker then becomes the active routine 
marker. 

Now, if a normal area marker trips, this encounter will have no 
effect on the current routine or on the active routine stack. When a 
normal area marker trips, it simply becomes the active area, which 
means that the profiler forgets the previously active area. The 
currently active routine, however, remains on the stack until the 
profiler encounters a return statement. 

When a return is issued within an active routine, the area marker 
associated with that routine becomes inactive. The routine on top 
of the profiler's active routine stack pops off the stack and 
becomes the active routine, until a retiim statement executes 
within that routine, or until another routine-entry area marker is 
tripped. 

Thus the profiler can maintain a complete call history for every 
marked routine. If you have enabled Statistics I Callers for all 
marked routines, then each time a routine-entry area marker is 
tripped, the profiler saves the entire profiler call stack in a buffer 
linked directly to the routine-entry marker. 

If that caU stack is identical to a caU stack that was saved for a 
prior entry to this routine, the profiler increments a counter, 
rather than saving the caU stack again. If, however, the caU stack is 
different, the profiler allocates a new buffer and logs the profiler 
call stack to that new buffer. This makes it possible to maintain a 
record of every caU path to a routine and the number of times 
each caU path is traversed. 

The profiler's active routine stack is related to two menu settings: 

■ Statistics I Callers (set to either Enabled or Disabled) 

■ the Callers option for each marked area in the Areas window 

You gain finer control over logging call paths by using the local 
menus of the Module and the Areas windows. You can set the 
Callers option for each of the marked areas separately. Both the 
Callers command on the Module local menu and the Options 
command on the Areas local menu lead to a dialog box where you 
can specify Callers as All CaUers, Immediate Caller, or None. 
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■ All Callers means log the entire routine call stack each time the 
entry point is tripped. 

B Immediate Caller means log only the top entry on the routine 
call stack when the entry point is tripped. 

B None means don't log any routine stack information when this 
routine-entiy marker is tripped. 

By default, when you first profile a program, the Callers option 
for all routine-entry area marks is set to None. 

Enabling Statistics I Callers from the main menu is the same as 
setting the Callers option to All Callers for each area marker listed 
in the Areas window. However, once youVe hand-set any of the 
Callers options in the Areas window, setting Statistics I Callers to 
Enable won't change the value of the Callers options for any of 
the areas. 

Disabling the Statistics I Callers option at this point tells the . 
profiler not to log any stack information, but doesn't change the 
Caller settings in the Areas window. Neither does setting 
Statistics I Caller.) 



Sampling vs. 
counting 



77i/s happens only in passive 
mode. 



The profiler does not actually measure time: It comes up with a 
very accurate estimate of time based on information from timer 
tick counts. This is a form of statistical sampling. By taking regular 
periodic samples of the current area, and by keeping a count for 
each area (which increments each time that area is active when 
the timer interrupts), the profiler can estimate the time spent in a 
given area. 

The profiler knows the total time taken to run the program. It also 
knows the total number of times the timer interrupted the 
program. The time spent in a given area can be calculated as 

timearea = timer t^t^ * counts^rea I countst^tai 

This is not the true time spent in an area. If your program iterates 
over some routine at a frequency that is a multiple of the timer 
frequency (for example, a routine that generates a steady sound 
tone), the execution of a particular line (or area) might exactly 
coincide with most of the timer interrupts. This resonance could 
occur even though that line is not where the program is spending 
most of its time. This is rare, but possible. 
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If you suspect this sort of frequency collision, change the 
Statistics I Profiling Options I Clock speed value and compare the 
resulting profile to the previous one. 



Profiler memory use 



Figure 2.2 

Memory map for Turbo 

Profiler 



O 



The following figure maps memory usage when Turbo Profiler is 
running a program. 

Low memory 
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The profiler allocates memory for area information on the far 
heap. If you add areas while the program is running, the far heap 
will expand into the user program area to make room for new 
area variables and buffers. This is why, if you modify areas 
during a run, you should always reset the program with Run I 
Program Reset. If you don't, the results of a profile might be 
unpredictable; you could hang your computer. 
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Profiling strategies 



Improving your program's performance through profiling is not a 
simple linear process; you don't just profile the program, modify 
the source code, and call it a day. Profiling for improved 
performance with Turbo Profiler is dynamic and interactive. You 
collect statistics, analyze the results in a variety of windows, 
perhaps change the profiling parameters so you'll get different 
statistics, profile again, analyze again, modify the source code and 
recompile, profile again, analyze again, and so on. 

If you're not sure at first where the bottlenecks in your program 
are, go ahead and profile using Turbo Profiler's default settings. 
When you look at the results in the Execution Profile window, you 
get an idea of which routines in your program consume the most 
overall time. By looking at time and count data together, you find 
out which parts of the program are most expensive in terms of 
time per call. Armed with that knowledge, you can start zeroing in 
on your program's problem areas. 

Turbo Profiler provides several different report windows for 
analyzing the collected data; you can also print report window 
contents to paper or disk for a running account of performance 
improvements. In the report windows, you can look at your 
program's execution times and counts, file-access activity, DOS 
interrupts, and overlay activity, along with caU histories for 
routines. 
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For exfenslve coverage of 

profiling In general, there are 

many articles and books you 

can refer to. 



It's a good Idea to save ttie 

results of a profile tttat takes 

a long time to run. In case 

you want to come back and 

study ttie results later. 



What do you do with all this power and flexibility? How do you 
use Turbo Profiler for efficient and effective profiling? And what 
are the tricks of the profiling trade? Obviously, we can't answer 
aU of these questions in this chapter. We do, however, provide 
some general guidelines, techniques, and strategies to get you 
moving. 

The first time you run Turbo Profiler on a program, it 

B automatically scans through your .EXE file to find the main 
program module 

B sets area markers for the program 

B determines what source module contains the main part of your 
program 

B loads that main module into the Module window 

B positions the cursor at the main module's starting point 

The main module is the one that contains the first source line to be 
executed in your program. Area markers are "trip points" that 
mark the locations where you want to gather statistics; the 
number of markers set depends on the number of symbols found 
in your program's debug information. 

Whenever you exit Turbo Profiler, it saves information about the 
areas you set up for the currently loaded program in an area file 
named filename.TFA, where filename is the name of your program. 
Each time you load a program to profile. Turbo Profiler looks for 
a corresponding .TFA file. If it finds one, it automatically uses the 
area settings in that file. 

You can also save the results of a profile to a .TFS file with the 
Statistics I Save conunand. By default, the file name assigned to a 
statistics file is filename.TFS. You can use the default or change the 
name (in case you want to save more than one set of statistics for 
a single program). 



Preparing to profile 



The examples in Chapter 1 are small and simple; we designed 
them to show the general process of profiling. The problem in that 
chapter was to optimize the routine prime, rather than to identify 
specific program bottlenecks. 
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However, you actually need a profiler more when you're writing 
very large programs, rather than small ones, because you must 
identify which program fragments are bottlenecks before you can 
figure out how to optimize any given fragment. In many ways, it's 
easier to find the bottlenecks than it is to figure out what to do 
about them. 

Before profiling your program, adjust your source code so the 
profile statistics gathered are useful and sufficient. Once the 
source code is modified (or if it doesn't need to be), compile the 
program with debug information turned on. Then set the markers 
that tell the profiler where to collect statistics and what kind of 
statistics to collect. 



Adjust your 
program 



Selecting input data is 
important. 



The first thing to do is set up your program in a way that lets you 
find out what you need to know from the profile. For example, if 
you're writing an interactive program that gets a lot of input from 
the keyboard, you don't need to find out that most of your time is 
spent waiting for the user to press a key. 

Here are some basic techniques for finding bottlenecks in large 
programs: 

n Select data sets large enough to give you a useful profile. 

A string search program on a three-line file won't tell you very 
much. Likewise, searching for a short string found in nearly 
every line of a 10,000-line file will give a different kind of 
profile than searching for a long string found only once in 
10,000 lines. 

D If you know your program runs quickly, set the profiler to 
collect statistics over several runs. (Modify the Run Count 
setting in the Profiling Options dialog box.) 

D Modify the program to work independent of keyboard input, or 
remove any areas that have code doing keyboard input. 

Read data numbers from a file or use a random number 
generator to stuff numbers in an array. The main idea is to 
select data thaf s typical of the real-world data the module 
operates on. 

o Isolate the modules of the program you know need 
improvement. 
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Compile your 
program 



Files that you've compiled for 

debugging wttti Turbo 

Debugger can be t)andled 

by Turbo Profiler \Mthout 

recompllatlon. 



After you've adjusted your program so that the projfiling session 
won't become a wild goose chase, compile it again with debug 
information turned on. 

To use Turbo Profiler with Borland products, you must have 
Turbo Pascal 5.0 or later. Turbo C 2.0, Turbo C++, or Turbo 
Assembler 1.0 or later. You must compile your source code with 
full sjrmbolic debugging information turned on. 

■ Turbo Pascal: Standalone Debugging and Debug Information 
must be set to On. 

■ Turbo C++: The Standalone radio button must be selected. 

■ Turbo C: Standalone must be specified in Debug I Source 
Debugging. 

■ Turbo Assembler: Source code must be assembled with the /zl 
command-line option and linked with TLINK, using the /v 
option. 

You can also run Turbo Profiler programs compiled with a 
Microsoft C compiler or assembled with MASM, if you convert 
them with TDCONVRT or TDMAP. (See doctmientation for 
Turbo Debugger utilities included in the MANUAL.DOC file on 
disk.) 

To run Turbo Profiler, you need both the .EXE file and the original 
source files. Turbo Profiler searches for the source files in these 
directories, in this order: 

1. in the directory in which they were found at compile time (this 
information is included in the executable file.) 

2. in the directory specified with the Options I Path for Source 
command 

3. in the current directory 

4. in the directory containing the .EXE program being profiled 



Set profile areas 



Once you've adjusted your program so you can concentrate on the 
troublesome areas and compiled it with debug information 
turned on, you're ready to run it through the profiler and coUect 
statistics for individual areas. You can start out by profiling your 
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whole program in general, then focus in more and more detail as 
you find the trouble spots. Start by accepting the default area 
settings — ^Turbo Profiler sets default areas based on the density of 
the symbols it finds appended to the executable file. 

An area, remember, is a location in your program where you want 
to collect statistics: An area can be a single line, a construct such 
as a loop, or an entire routine. An area marker sets an internal 
breakpoint. Whenever the profiler encounters one of these 
breakpoints, it executes a certain set of code — depending on the 
options that you've set for the area in question. TTiis profiling code 
could be a bookkeeping routine or a simple command to stop 
program execution. 

These are the actions the profiler can perform when execution 
enters an area: 

Operation What it does 

Normal Activates the default counting behavior (collects 

execution time and counts for all marked areas). 

Enable Turns on the collection of statistics (if they've been 

previously disabled). 

Disable Turns off the collection of statistics, but lets your 

program keep running. When your program enters an 
area where the action is set to Enable, the profiler 
resumes data collection. 

Stop Stops the program, and returns control to the Turbo 

Profiler environment. At that point, you can examine 
the collected statistics, then resume execution. 

By default. Turbo Profiler counts the number of times execution 
enters an area and how long it stays there. You can change what 
the profiler does when an area executes by setting the Operation 
option in the Area Options dialog box — accessed through the 
Module or Areas window local menus. 

When you're setting areas in your program before running a 
profile, you should consider these questions: 

a How many areas should statistics be collected for? 
m Which parts of the program should be profiled? 
□ What should happen at each marked area? 
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What level of detail do 
you need? 



Suggestion 



You must first decide how much information you want. Keep in 
mind how large your program is and how long it takes to run. 

■ For a small program, you probably want statistics for every 
executable line — the maximum level of detail. 

■ For large programs, you need less detail; just profiling the 
amount of time spent in each routine is probably enough. 

"Large" is a bit vague: You need to take into account the number 
of modules of source code, the number of routines, and the 
number of Hnes. 

If your source consists of 10,000 lines in ten modules, you should 
probably analyze only one module at a time in active analysis. 
(Your program is factored into discrete functional modules, 
right?) 

On the other hand, if your program is less than 100 lines and you 
need detailed analysis, you probably want to collect statistics for 
all lines. 

If your program runs in less than five seconds, you'U get more 
accurate profile results if you set up multiple runs with averaged 
results. (Set the number of runs with the Statistics I Profiling 
command.) If the program takes an hour to run (not counting 
profiler overhead), be careful not to set so many areas that you 
slow down execution to an unacceptable crawl. 

You divide your program into a number of areas by selecting Add 
Areas from the Module window's local menu, then run your 
program to accumulate statistics for each area. 

If you don't teU Turbo Profiler how to divide your program, it 
uses a default scheme to intelligently select appropriate areas in 
your program. Based on information it finds in a program's 
symbol tables. Turbo Profiler selects one of several default options 
for setting areas in a program. 

■ If there are few symbols in the table, and there is a single 
module. Turbo Profiler selects Every Line in Module as the 
default area setting. 

■ If there are many symbols and several modules. Turbo Profiler 
selects All Routines as the default area setting. 

If your program is very large, profile it first in passive mode to get 
the big picture, then select areas for more detaied analysis. 
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What type of data do 
you need? 



When should data 
collection start? 



For each area in your program. Turbo Profiler accumulates the 
following default information: 

□ the number of calls to the area 

o how much time was spent in the area (active mode) 

m how many clock ticks occurred while the area executed (passive 
mode) 

You can also collect more extensive information during the 
profiling session. 

□ By enabling Statistics I Callers and setting Call Stack options in 
the Area Options dialog box, you can track which routines caU 
a marked routine — how often and through what pathway. 

Q With the Statistics I Files option enabled, you can monitor your 
program's file-access activity. 

□ The Statistics I Interrupts option, when it is enabled, records 
your program's interrupts. 

Q You can monitor your program's overlay file activity by 
enabling the Statistics I Overlays option. 

Once you've enabled the appropriate Statistics menu options, you 
can open the corresponding profile report windows (through the 
View menu), then caU up each window's local menu to specify 
details about how you want the data collected. 

Remember, to get the Turbo Profiler reports you want, you need 
to set options before you run the program. 

Often, you only want to collect timing information when a certain 
portion of a program is running. To do this, start the program 
executing without collecting any information; set the Statistics I 
Accumulation option to Disabled. You can determine the 
Accumulation option's setting at any time by bringing up the 
File I Get Info box and checking the status of Collection. 

With Accumulation disabled, you must set an area marker to 
Enable for the area where you want data collection to start, then 
set another marker to Disable for the area where you want data 
collection to stop. The actual number of start and stop points you 
set is determined by the amount of available memory; generally, 
you can set as many as you need. 
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How do you want time 
data grouped? 



Which data do you 
want to look at? 



The profiler can keep each routine's execution-time statistics 
separate from others, or it can combine routines' times with those 
of the routines calling them. 

By default, as soon as an active routine caUs a routine that has an 
area marker, the profiler puts the calling routine on the call stack 
and makes it inactive. The profiler associates any timer counts 
made while program control is in the routine with that routine 
only, not with the caller. 

However, if you specify that the caller should use a combined 
clock (rather than a separate clock), the profiler associates timer 
ticks that occur while control is in the routine with both the 
routine and the caller. 

■ If routine A makes no routine calls to other routines, it (routine 
A) won't appear as an area in the Execution Profile window. 
Instead, the routine that called A appears with a time 
equivalent to its own execution time plus the time of routine A. 

■ If routine A does call other routines, it (routine A) appears as an 
entry in the Execution Profile window. The time associated 
with routine A is the time required to execute A's routines, but 
not A's self time (the time spent in its own execution). 

Turbo Profiler's default analysis mode uses a separate timer for 
each marked routine. So normally, the time spent in a routine is 
measured exclusive of calls to routines. If you want a routine's 
time data to include time spent in routines, choose Combined 
under Timing in the Areas window's (Options) dialog box. 

It's important to know how to control the amount of information 
Turbo Profiler collects and subsequently displays, particularly if 
you want detailed information about just part of a large program. 
Turbo Profiler provides two ways to control how much 
information you view about your program: 

■ Before you profile, you can lunit the collection to specific areas 
and t3^es of data by setting options and parameters. 

■ After the profile, you can filter the collected statistics (without 
erasing any) and display only the data you're currently 
interested in. 

In the Module, Areas, and Interrupt windows, you can specify 
which parts of your program you want Turbo Profiler to collect 
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o 



information about, and how much information to collect. You can 
choose to make data collection as coarse as aU routines in a 
module or as fine as a single statement. You can choose to collect 
time-related data only {by setting the analysis mode to Passive), or 
you can choose to collect the full gamut of data, including 
complete call-stack histories, all file-access and overlay activities, 
and aU DOS interrupt calls. You can slow down or speed up the 
profiler's timer, thus decreasing or increasing the resolution of 
data collected (passive mode only). 

There's a basic tradeoff in how much data you choose to collect: 
The more information Turbo Profiler collects, the slower your 
program runs and the more memory it needs to store the collected 
statistics. 

Once youVe collected the data, you can use commands in the 
profile report windows to temporarily exclude the data you don't 
want to look at from the displayed statistics. (See page 56 for 
more information about filtering displayed statistics.) 



Profiling your program 



You might not know if a 

profile Is worth saving until 

you iool< at several Execution 

Profile windows. 



Once you've selected the areas, run the profile. You can save the 
resulting profile with the Statistics I Save... command. This 
command saves the statistics to a .TFS (Turbo Profiler Statistics) 
file. If you plan to save several different profile results, use some 
file-naming convention that uniquely identifies each of the runs 
(for example, RUNl.TFS, RUN2.TFS, and so on). This simplifies 
your task of comparing them later. 

After you save the .TFS file, you can study the profQe's results in 
the profile report windows, sorting and fQtering the displayed 
data as you explore their meanings. You won't lose any area 
markers or statistical reports, because all this inforn:iation can be 
reproduced (simply restore the profile from the .TFS file). In 
general, if a profile took a long time to create, save it unless you're 
absolutely sure you won't need it. 



What are you 

trying to fincri out? Normally, programmers use a profiler to get answers to one or 

more of these questions: 

m How efficient is this algorithm? (Algorithm testing) 
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Table 3.1 
Ways of using a profiler 



Testing algorithms 



■ Is this program doing what I think it is? Is all of it running? 
{Verification and testing) 

■ How long does each routine run? How much time does the 
program spend using various resources? {Execution timing and 
resource monitoring) 

■ What's the structure of this code? {Code structure) 

The following table relates why you're profiling to the type of 
information you're likely to gather. 

Purpose of profile Type of information gathered 



Algorithm testing 

Program testing 
and verification 

Execution timing 
and resource 
monitoring 



Program structure 
analysis 



Line<ount information 
Dynamic call history 

Execution-count at the routine level 
(possibly at line level) 
Dynamic call history 

Execution time 
Execution counts 
Interrupt activity 
File-access activity 
Overlay activity 

Dynamic call history 

File-access activity 

Execution profile (time and counts) 

Interrupt activity 

Overlay activity 



If you're analyzing an algorithm, you'U probably concentrate on a 
small number of routines, so line count information matters more 
than execution times do. You need to do the following: 

1. Isolate the algorithm and its supporting routines by marking 
them as an area. 

2. Make sure you've set area markers for all lines in all routines 
that implement the algorithm in question. 

The examples in Chapter 1 demonstrate algorithm analysis, 
especially as it relates to execution time statistics. 



Verifying and testing In program verification and testing, line-count information is more 
programs pertinent than execution times. But since the verification and 

testing process looks at the program as a whole, you want to see 
how everything works together in an integrated system. 
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Profiling a program while you run it through standard tests can 
point out areas of the program that execute very little or not at all. 
For example, by studying call paths in the Callers window and 
printing out a source-code listing (annotated with execution 
counts) from the Module window, you can verify that every 
statement in your source code has actually executed. 

Because you deal with large pieces of code when you test and 
verify programs, you don't need as much detail as you do for 
algorithm analysis. However, ifs still useful to know how many 
times a routine has been called. And, if you want to organize the 
test down to groups of routines that constitute some hierarchy, the 
execution-coimt information can help prove that every path in a 
switch statement or a conditional branch has executed at least once. 

Timing execution and For timing a large program to see where it's slow, you rarely need 
monitoring information at the line-count level. In execution timing, you need 
performance to know two things: 

1. how much time is spent in individual routines 

2. what times propagate from low-level routines to higher-level 
routines 

Before timing a program's execution, you need to set areas for all 
routines with source code. In very large programs, limit your 
selection of area markers to a single module. 

Once you've set the area markers in a single module, profiling 
becomes a matter of successive grouping and refinement. These are 
techniques you use to refine the profiling process: 

■ Use filters to temporarily mask out unwanted information (with 
the Execution Profile window's local Filter command). 

■ Unmark routines whose statistics you don't want (with the local 
Remove command in the Module, Execution Profile, and Areas 
windows). 

■ Combine the timer counts for specified routines (with the Timer 
option, which you set from either the Statistics I Profiling 
Options... command or the Areas window's local Options... 
command). 

If you're not completely familiar with the program you're 
profiling, you can use execution timing and performance 
monitoring in conjunction with studying the unfamiliar code. 



Chapters, Proving strategies 



49 



studying unfamiliar 
code 



Figure 3.1 
The Callers window 



One of the best ways of studying code you don't know is to 
analyze the dynanuc call history that Turbo Profiler generates in 
the Callers window. This history shows the program's structural 
hierarchy. Although you can see only one routine's call paths at a 
time in the Callers window, you can print all recorded call paths by 
choosing Print I Statistics with the CaUers window open. 




By noting a program's called routines, their callers, and the number 
of times the program traverses each call path, you can see which 
routines are most important. You can also predict which higher- 
level routines wiU be affected by changes you make to lower-level 
routines. 

By looking at execution times and counts, you can get a sense of 
the program's important routines. File and overlay monitoring 
reveal any temporary fQes opened and closed during program 
execution as well as any overlays swapped into memory. This 
information is harder to find through lexical program analysis. 

The profiler's link between the Execution Profile, Module, and 
Areas windows enables you to move back and forth quickly to 
specified symbols, thus revealing the connections between 
functionally related but physically separated pieces of source code. 



Which analysis 

mode do you 

use? 



One important consideration when you're profiling is whether to 
use active or passive analysis. You set the mode under Profile 
Mode in the Profiling Options dialog box (choose Statistics I 
Profiling Options). Turbo Profiler's default mode is active analysis; 
it collects execution times and execution counts automatically, as 
well as any other data (such as call histories or DOS interrupts) 
that you've enabled in the Statistics menu. If your program runs 
very slowly and you can do without execution counts and call 
histories, use passive analysis; in passive mode, the profiler collects 
only time-related statistics for areas (such as execution times. 
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interrupt calls, and file activity), and your program runs much 
faster. 



Active analysis 



See the section 'How to 

speed up profiling' below for 

ott)er ways to make your 

protWng go faster. 



When you profile in active mode, it matters how fi-equently 
program execution trips area markers. For instance, you can mark 
every line in a program except a loop statement, but if the program 
spends 95% of its time inside that loop, the number of areas set 
won't slow the program much. 

The profiler slows down program execution if it must perform a lot 
of bookkeeping every time it executes a source statement. If that 
happens, you can always switch to passive analysis, which turns 
off all automatic calls to expensive bookkeeping code the profiler 
normally makes each time program execution trips an area marker. 



Passive analysis 



Passive analysis doesn 't add 

noticeable overttead to 

program run time, but it does 

sacrifice some detail In ttte 

resulting reports. 



Some things to watch 
out for 



In passive analysis. Turbo Profiler interrupts your program's 
execution at regular intervals to sample the value of the program 
counter, CS:IP. If the sampled value points to an address inside an 
area that you're monitoring (a marked area), the profiler 
increments the ticks in that area's timer compartment. If the value 
in the CS:IP does not point to an address inside a marked area (for 
example, it points to an address within a DOS interrupt or BIOS 
caU), the profiler throws out that timer tick. 

It's hard to interpret the results of passive analysis unless your 
program runs a long time, or unless you accumulate timing 
statistics over many runs. Some areas of your code might never 
show up even though they execute, because they're never being 
executed at the time the profiler interrupts the program's 
execution. 

When you set passive analysis, there is no noticeable slowdown in 
program execution. However, you might not be able to get all the 
information you require. You can't get count information or callers 
information, but you can monitor interrupt calls and file activity. 

When you're profiling in passive mode, you'll get greater statistical 
accuracy by running your program several times (set Run Count in 
the Profiling Options dialog box to a value greater than 1). 

Some of the data you collect under passive analysis might be 
misleading if you don't take these points into consideration when 
you analyze the results: 
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B If your program does disk I/O, the profiler attributes file-access 
time to the calling routine under active mode, but not under 
passive mode. 

■ If your program caUs an interrupt thafs not marked as an area, 
the profiler attributes the intemipt's time to the calling routine in 
active mode, but tosses out the interrupt's time in passive mode. 



Profiling object- 
oriented 
programs 



In general, profiling object-oriented programs is not much different 
from conventional profiling. You can treat them just like ordinary 
programs and consider each method to be just like a caU to a 
routine. 



How to speed up 
profiling 



Even if your program runs 

slower. Turbo Profiler still 

keeps track of timing 

information properly. 



Each time your program enters a routine that you have defined as 
a data-coUection area. Turbo Profiler must perform certain 
processing Cl^ookkeeping" code). The execution speed of a 
program under the control of Turbo Profiler depends on how 
frequently area markers are tripped and on the kind of information 
being collected for the most frequently tripped areas. The greater 
the level of information being collected (particularly caU stack 
history), the longer it takes to execute bookkeeping code associated 
with an area. 

Sometimes your program speed might be unacceptably slow under 
Turbo Profiler. That might be because your program is frequently 
calling a deeply nested routine with caU-stack tracing set to All 
Callers for All Areas. If you've defined this deeply-nested routine as 
an area. Turbo Profiler will spend a lot of time keeping track of the 
caUs to it. 

To determine if your program is frequently calling a low-level 
routine, switch to the Execution Profile window and display the 
areas by execution counts. (Set the local menu Display option to 
Counts.) This displays an execution-count histogram sorted by the 
number of times each area is executed. 

If the program caUs one or more routines much more frequently 
than the rest, you can exclude them from the list of displayed areas 
with the Execution Profile window's local FUter I Current 
command. You can also unmark areas with the local Remove 
command in the Module, Areas, and Execution Profile windows. 
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How to improve 

statistical 

accuracy 



If you don't collect enough data (because your program runs too 
fast for the profiler to gather a statistically significant number of 
data points) or if you collect a skewed data set (because of 
resonance; the profiler's timer-tick frequency coincided with the 
execution frequency of some part of your program), you won't be 
able to make informed decisions about the changes needed in your 
source code. Here's what to do if either of these problems should 
occur. 



Insufficient data 



To improve the accuracy of timing statistics and to get a 
statistically significant average, run your program more than once, 
using the Run Count option of the Profiling Options dialog box. 
When your program terminates and you run it again, the profiler 
adds the times for the new run to times accumulated for previous 
runs. This continues until you've run your program the number of 
times specified in the Run Count option. 



Resonance 



Changing the clock speed 

can only be done in passive 

mode; active mode doesn't 

use clock ticks. 



If resonance is causing the profiler to return inaccurate data, use 
the Clock Speed setting in the Profiling Options dialog box to set 
the profiler's clock tick speed anywhere between 18 and 1,000 ticks 
per second. Choose a speed that is not an integral multiple or 
fraction of the speed that is causing the resonance. For example, if 
your program exhibits resonance at 100 ticks per second, try 70 or 
130 ticks per second. (If you suspect that resonance is causing 
biased statistics, try different clock speeds that are not integral 
multiples, and compare the collected statistics. If resonance is the 
problem, the various sets of statistics will vary considerably.) 

The faster the clock speed, the more accurately Turbo Profiler can 
determine where your program spends its time. 

Will setting the clock speed to 1000 ticks per second produce 
incredibly accurate timing information? Not necessarily. The faster 
you set the clock speed, the slower your program will run (because 
Turbo Profiler must perform certain lookup operations each time a 
clock tick occurs). So if you want greater accuracy than the default 
100 ticks per second, increase the clock speed until you reach an 
acceptable compromise between accuracy and execution speed. 
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Some tips for 
profiling overlays 



Overlays allow large programs to run in limited memory by 
storing portions of the code on disk, and loading that code only as 
needed. If you use overlays, the program's modules share the same 
memory — thereby reducing total RAM requirements. 

Unfortunately, swapping code in and out of memory can lead to 
slow program execution because it wastes tune accessing disk 
drives. Because even a fast disk drive is still the slowest storage 
device in most PCs, improper overlay management can 
dramatically reduce performance. To make a difficult situation 
worse, the overlay manager code in the compUed program is 
normally hidden. Turbo Profiler brings overlay management code 
out in the open so you can adjust your program's overlay behavior. 

To fine-tune overlay performance, you need to choose the right 
overlay buffer size, select algorithms for managing overlays in the 
buffer, and set other parameters that can help keep the most 
frequently-used overlay modules in memory for longer periods of 
time. You can reduce "thrashing", which results from too many 
disk accesses as the program reads overlay files, by keeping 
frequently used overlays in memory longer. 

Statistics displayed in the profiler's Overlay window include 

■ the number of times your program loads each overlay from disk 

■ the time-ordered event sequence in which your program loads 
overlays 

The load-count and execution-time information is useful for 
determining which overlays should stay in RAM longer. By 
comparing this data with a profile of non-overlay routines, you can 
decide which modules should be overlays and which shouldn't. 

With the overlay event history, you can choose optimal algorithms 
for overlay buffer management. By examining a list of overlays and 
seeing when and how often each was loaded, you can decide 
which main program modules might work better as overlays, and 
which overlays might benefit from being made part of your main 
program. 
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Interpreting and applying the profile results 

OK, so you've decided what profile statistics you want to collect, 
adjusted your program accordingly, and run it enough times to 
gather a statistically significant (if not downright daunting) set of 
data. Now what? 

Now comes the fun part. First you analyze the data to figure out 
what the profiler is telling you, then you apply that new-found 
knowledge to your source code to make your program faster and 
more efficient than ever. 

How to analyze 

profil© data The Turbo Profiler windows you'll use to study the collected 
statistics fall into two categories: program source windows and 
profile report windows. 

Turbo Profiler's program source windows are the Module, Areas, 
Routines, and Disassembly (CPU) windows. Before running the 
profile, you mainly use source windows to set areas and to specify 
profiling actions at the marked areas. After you examine the profile 
statistics (in one or more report windows), you use source 
windows again to analyze your program's source code. 

Turbo Profiler's report windows are the Execution Profile, Callers, 
Overlays, Interrupts, and Files windows. You use report windows 
to display profile statistics gathered from your running program, 
so you can evaluate the collected data and determine where 
changes in the source code might improve your program's 
performance. 



Execution Profile 
window 



This window wUl be your primary focus for improving the 
performance of your program. In general you will want to examine 
those lines of source code which account for most of the program 
execution time. Next, look for lines (or routines) which have a high 
ratio of execution time to execution count. And finally, it is always 
good form to check on the routines which account for the most 
"per caU" execution time. 
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Callers window 



Once you have isolated a routine that you wish to improve, use the 
Callers window to locate aU of the areas in your program which 
call the selected routine. The Callers window displays the number 
of times the routine was called, and the source of those calls (the 
caUer). 



Overlays window 



The Overlays window will allow you to detect excessive overlay 
caUs which will then become candidates for placement into a non- 
overlaid module (unit). 



Interrupts window 



The Interrupts window will reveal all of the (selected) interrupts 
made by your program. This revelation may prompt you to 
combine video output for some lines of code. Or for file-intensive 
programs, suggest that disk I/O be buffered. 



Files window The Files window quickly discloses the number of reads and writes 
performed to the files manipulated by your program. In I/O 
intensive applications this window will point out very quickly 
which fQes deserve your attention. 



How to filter collected 
data 



Table 3.2 

Local menu commands for 

filtering collected statistics 



The Execution profQe report window provides local menu com- 
mands for temporarily or permanently filtering data out of the 
current display. Here's a table summarizing the profiler's filtering 
options: 



Window 



Local menu 
command 



Execution Filter 
Profile 



Remove 



What it does for you 



Temporarily removes the current 
area's statistics, or shows only the 
current module's statistics, or 
restores all collected statistics to the 
window. (You choose Current, 
Module, or AU from the Filter 
menu.) 

Permanentiy erases the current 
area's statistics from the collected 
data. Use with caution! 



Files 



Collection (top pane) Disabled, disables file statistics 
collection. 
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Table 3.2: Local menu commands for filtering collected statistics 
(continued) 



Detail (top pane) 



Display., 



Interrupts Remove (top pane) 

Display (bottom 
pane) 



Overlays Display 



Disabled, displays only file open 
and close activities. Enabled, also 
displays file read and write 
activities. 

Displays each event either as a bar 
graph element, or as text showing 
the exact time and duration of the 
event. 

Removes the currently selected 
interrupt from the top pane. 

Displays an interrupt's statistics as 
either (1) summary histograms of 
time, calls, or both, or (2) a detailed 
sequence of events. 

Displays each overlay's profile 
statistics as either (1) Count, a 
summary of memory consumed 
and times loaded, or (2) History, a 
detailed sequence of events, with a 
line of data for every time the 
overlay loaded. 



When you choose Remove from the Execution Profile's local menu 
to permanently filter out an area's statistics, the profiler 

D adjusts the report by discounting time spent in that area 

B adjusts the percentages of remaining areas by calculating them 
as percentages of the revised total time 
(revised toted time = total profile time — time for the removed area) 
u unmarks that area in the Module window 
Q removes the area from the areas list in the Areas window 

Revise your 

prOQrQin Here is a general plan of attack for finding routines where simple 
changes in control constructs can improve your program's 
performance. 

1. Look for large routines with a disproportionate share of 
execution time, or for routines with a large number of calls. 
Working from the highest level of your program, follow flow of 
control through successive levels of calls, looking for places to 
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optimize by reducing or eliminating excessive calls and 
operations. 

2. Look for statements and routines that have a high ratio of time 
to count. From the Execution Profile window's local menu, set 
Display to Both or Per Call. Then look for those areas that show 
a long time magnitude bar and a short count magnitude bar. 
Statements and routines of this sort usually represent an 
inefficient segment of code. Recode them to produce the same 
result in a more efficient way. 

3. As a last resort, you can optimize the program's innermost 
loops; here are some techniques: 

■ unroll loops 

■ cache temporary results calculated on each iteration 

■ put calculations for which results don't change outside loops. 

■ hand-code assembly language 

Usually you'll see less improvement with inner-loop optimization 
than you'U see if you modify control constructs, algorithms, or data 
structures. 

Besides these three general procedures, here are some specific 
things you can do to improve your program's performance: 

■ Modify data structures and algorithms 

■ Store precomputed results 

■ Cache frequently accessed data 

■ Evaluate data only as needed 

■ Optimize loops, procedures, and expressions 

Modify data structures Use more sophisticated data structures or algorithms. A Quicksort 

routine will generally operate faster than a bubble sort for a 
random distribution of key values. Consult a book on data 
structures and algorithms for other examples. 

Switch from real numbers to integers for fast calculations, such as 
window and string management for screen I/O and graphics 
routines. Use long integers for data manipulation or any other 
value that does not require floating point precision. 

Instead of sorting an array of lines of text, add an array of pointers 
into the text array. AU text access occurs via the pointers. To sort or 
insert a new line of text, you only need to reorder the pointers, 
rather than entire lines of text. 
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store precomputed 
results 



Build a precomputed sine table, then look up sine as a function of 
degrees based on an integer index. 



Cache frequently 
accessed data 



Evaluate data as 
needed 



C buffers low-level character input from files. The getc routine 
reads a whole sector of bytes from the disk into a buffer, but 
returns only the first character read. The next call to getc returns 
the next character in the buffer, and so on imtil the buffer is empty, 
in which case getc reads another sector in from disk. The Read 
routine does exactly the same thing in Pascal. 

Turbo Pascal has the SetTextBuff routine, which can also help to 
reduce disk accesses. By use of this routine to allocate a large text 
buffer on the heap, you can reduce disk file access for text. 

In an interactive editor or file-dump utility, you can keep a number 
of buffers that are updated while the program waits for user input. 
You might have two buffers that always contain screenfuls of 
information read from the beginning and the end of the file. 
Another two buffers can keep the previous and next screenful of 
bytes in the disk file relative to the position currently onscreen. 
This way, for those file-navigation commands the user is most 
likely to select, your interactive program can update the screen 
without disk access. 

Structure the order of conditional tests and switches so that those 
most likely to yield true results are evaluated first. 

For a large table of lookup information, evaluate entries only as 
you need them, and use a supplemental array to track entries that 
have already been computed. 

You might only need to calculate the length of a line when you 
need to reformat output — not each time a new Une is read from a 
file. 



Optimize existing code 



Loops, procedures, and expressions all offer potential for 
improvement. 



Loops 

D Whenever possible, move calculations outside of loops. 
Repeatedly calculating the same value inside a loop is both 
time-consuming and unnecessary. 
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1 Store the results of expensive calculations (use Statistics I Save 
Option). 

For example, an insertion sort routine doesn't need to swap 
every pair of numbers as it works up an array. If you save the 
value of the starting element, the inner loop only needs to move 
the successive element down as long as that element is less than 
the starting one. When this test fails, you insert the stored value 
at the current position. This process replaces the expensive swap 
operation for each element called for in the traditional insertion 
sort algorithm. 

If two loops perform similar operations over the same set of 
data, combine them into a single loop. 

Reduce two or more conditional tests in a loop to a single test, if 
possible. 

For example, add an extra element to an array and initialize it to 
some sentinel value that will cause the loop test to fail. (This is 
how C handles text strings.) 

Unroll loops. 

For example, replace this 

for (x = 0; X < 4; x++) 
y += items [x]; 

with this 

y += items [0]; 

y += items [1]/ 

y += items [2 ]; 

y += items [3]; 



Routines 

■ Rewrite frequently called routines as inline routines, or replace 
their definitions with inline macros. 

■ Use coroutines for multipass algorithms that operate on large 
data files. (See the setjmp and longjmp routines in C.) (In Pascal, 
investigate procedural types that allow you to use procedures and 
functions much like variables to execute coroutines.) 

■ Recode recursive routines to use an explicitly managed data 
stack. 



Expressions 

B Use compile-time initialization. 
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1 Combine returned results in a single call. 

For example, write routines that return sine/ cosine, quotient and 
remainder, or x-y screen coordinates as a pair. 

Replace indexed array access with pointer indirection. 



Wrapping it up 



In this chapter, we've covered most of the things you need to 
consider before, during, and after a profiling session. We've 
explained how to prepare your program, and yourself, for the 
profile; we've given you some hints and caveats about the process 
of profiling; and we've given you some ideas about how to apply 
the results after you've run the profile. In the next chapter, we 
describe each menu item and dialog box option in the Turbo 
Profiler environment. 
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The Turbo Profiler environment 



Turbo Profiler makes it as easy and efficient as possible for you to 
profile your programs. When you start Turbo Profiler, everything 
you need is literally at your fingertips. That's what an environment 
is all about. 

The Turbo Profiler environment also boasts these extras to make 
program profiling smooth: 

□ multiple, movable, resizable windows 

□ mouse support for any mouse compatible with the Microsoft 
mouse version 6.1 

D dialog boxes to replace multilevel menus 

Part 1 : The environment components 

There are three visible components to the integrated environment: 
the menu bar at the top, the window area in the middle, and the 
status line at the bottom. Many menu items also offer dialog boxes. 
Before we discuss each menu item in the environment, we'U 
describe these more generic components. 

The menu bar 

Ond menus Turbo Profiler has global and local menus. Global menus are ones 
you access via the menu bar, and local menus are ones you access 
from within a window. 
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The menu bar is your primary access to all the global menu 
commands. In addition, it displays a program activity indicator 
on the right side that tells, for example, whether the profiler is 
READY for you to do something, RUNNING your program, or WAlTing 
while it processes a processor-intensive task. The only time the 
menu bar is not visible is when you're viewing your program's 
output in the user screen. 



Choosing menu 

commands from the 

keyboard 



To cancel an action, press 
Esc. 



Here is how to execute global menu commands using just the 
keyboard: 

1. Press F10. This makes the menu bar active, which means the 
next thing you type pertains to it, and not to any other 
component of the environment. 

You see a highlighted menu title when the menu bar is active. 
The menu title thaf s highlighted is the currently selected menu. 

2. Use the arrow keys to select the menu you want to display. 
Then press Enter. 

As a shortcut for this step, just press the initial letter of the 
menu title. (For example, press Fto display the Files menu.) 

If an ellipsis (...), follows a menu command, choosing the 
command displays a dialog box. If an arrow (►) follows the 
command, the command leads to another menu. 

3. If the command opens another menu, use the arrow keys 
again to select the command you want. Then press Enter. 

Again, as a shortcut, you can just press the highlighted letter 
of a command to choose it, once the menu is displayed. 

At this point. Turbo Profiler either carries out the command, 
displays a dialog box, or displays another menu. 



In addition to the global menus that you access through the menu 
bar, each of Turbo Profiler's windows has its own unique local 
menu (or menus). When you're in a window, press Alt-F10 to bring 
up the local menu. 

When the local menu pops up, use the arrow keys to select the 
command you want and press Enter, or press the highhghted 
letten Once you choose a local menu command. Turbo Profiler 
either carries it out, displays a dialog box, or displays another 
menu. To activate a local menu item directly (without bringing up 
the menu), press the Alt-(ietter) hot key, where letter is the menu 
item's highlighted letter. 
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Choosing menu 

commands with the 

mouse 



To choose commands from global menus with the mouse, click 
the desired title on the menu bar to display the menu, then click 
the desired menu command. You can also drag straight from the 
menu title down to the menu command. Release the mouse 
button on the command you want. (If you change your mind, just 
drag off the menu; no command will be chosen.) 

To choose the active window's local menu commands, click the 
mouse's right button to pop up the local menu, then chck the 
desired menu coirunand. 



Shortcuts 



Turbo Profiler offers many quick ways to choose menu 
commands. For example, with a mouse you can combine the 
two-step process into one: Drag from the menu title down to the 
menu commands, then release the mouse button when the 
command you want is selected. 

From the keyboard, you can use keyboard shortcuts (or hot keys) 
to access the menu bar and choose commands. Here's a Hst of the 
shortcuts available: 



Press this shortcut... 



To accomplish this. 



Ctrl and the highlighted 
letter of the local menu 
command 

Alt plus the highlighted 
letter of the menu command 

The highlighted 
letter of the dialog box 
component 

The hot key combination 
listed next to a menu command. 



Carry out the local menu command 



Display a menu from the menu bar 

Execute that menu command or 
select that dialog box component 

Carry out the menu command 



Turbo Profiler 
windows 



Most of what you see and do in the Turbo Profiler environment 
happens in a window. A window is an area of the screen that you 
can move, resize, zoom, layer, close, and open. 

You can have many windows open in Turbo Profiler (memory 
allowing), but only one window can be active at any time. The 
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Figure 4.1 
A typical window 



active window is the one that you're currently working in. Any 
command you choose or text you type apphes only to the active 
window. 

Turbo Profiler makes it easy to spot the active window hy placing 
a double-lined border around it. The active window always has a 
close hox. If your windows are overlapping, the active window is 
also the one on top of all the others (the front most one). 

There are several types of windows, but most of them have these 
seven things in common: a title bar, a close box, two scroll bars, a 
resize comer, a zoom box, an iconize box, and a window number 
(1 to 9). 

This is what a typical Turbo Profiler window looks like: 



The HHMffiH contains 
the naroe of the NindoN 



You click the 
to 



quickly close 
the NindoN 



The IN'lillVJIiB n has 
an Icon you click to 
shrink the wIndoN to 
an Icon. 



The W»liill'!>W contains 
an Icon you click to 
either enlarge or 
shrink the window 
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Window management 



Some windows are divided into two or more panes for displaying 
different kinds of information. Individual panes often have their 
own local menu. 

The following table provides a quick rundown of how to handle 
windows in Turbo Profiler. You can perform these actions with a 
mouse or the keyboard. 



Table 4.1 : Manipulating windows 



To accomplish this. 



Use one of these methods... 



Open a window 
Close a window 

Activate a window 



Choose View to open a profiler window that's not already open. 

Choose Close from the Window menu or press Alt-F3, or Click the 
window's close box. 



View the window^ contents 



Click anywhere in the window, or 

Press Alt plus the window number (1 to 9, in the upper right border of 
the window), or 

Choose Window and select the window from the list at the bottom of 
the menu, or 

Choose Next from the Window menu (or press F6) to make the next 
window active (next in the order you first opened them). 

Use the cursor keys to scroll the window up and down or left and right, 
or 

Use the mouse to operate the scroll bars: 

■ Click the direction arrows at the ends of the bar to move one line or 
one character in the indicated direction. 

■ Click the gray area in the middle of the bar to move one window size 
in the indicated direction. 

B Drag the scroll box to move as much as you want in the direction you 
want. 

Move the active window Drag its title bar, or any border character (=)s that is not a scroll bar. 

Choose Size/ Move from the Window menu (or press Ctrl-F5), use the 
arrow keys to place the window where you want it, then press Enter. 

Resize the active window Drag the resize corner. 

Choose Size/Move from the Window menu (or press Ctrl-F5), press 
Shift-iaiTov! key) to change the size of the window, then press Enter, or 

Drag the right or bottom border to resize the window in that direction 
only. 

Click the zoom box, or 

Double-click the window's title bar, or 



Zoom the active window 
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Table 4.1 : Manipulating windows (continued) 



Choose Zoom from the Window menu, or press F5. 

Click the iconize box, or 

Choose Iconize/Restore from the Window menu. 

When a window is ftiUy zoomed, it has only an iconize box.([t]) When it 
is iconized, it has only a zoom box ([t]). 

Press Ted) or Shift-Tab, or 

Choose Window I Next Pane. 



Iconize the active window 



l\/love from pane to pane 



The status line 



The only time tlie status line is 
unavailable is whten a dialog 
box or menu is open. You 
must dose thie dialog box or 
menu before doing anything 
else. 



Dialog boxes 



The status line at the bottom of the Turbo Profiler screen provides 
the following information: 

■ It reminds you of basic keystrokes and shortcuts applicable at 
that moment in the active window. (You will see that the status 
bar changes if you hold down Alt or Ctrl.) 

u It provides on-screen shortcuts you can click to cany out the 
action (instead of choosing the command from the menu or 
pressing the hot key on the keyboard). 

■ It offers one-line information on any selected menu command 
or dialog box item. 

The status line changes as you switch windows or activities. You 
can click any of the shortcuts to carry out the command. 

When you've selected a menu command, the status line changes 
to display a one-line summary of the routine of the selected item. 
For example, if the Options menu title is selected (highlighted), 
the status line displays the currently selected item in the Options 
menu. 



If a menu command has an eUipsis after it (...), the command 
opens a dialog box. A dialog box is a convenient way to view and 
set multiple options. 

When you're making settings in dialog boxes, you work with five 
basic types of controls: radio buttons, check boxes, action buttons, 
text boxes, and Hst boxes. Here's a typical dialog box that 
illustrates some of these items: 
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Figure 4.2 |j^ 
A typical diaiog box 



If you have a color monitor. 

Turbo Profiler will use different 

colors for various elements of 

the dialog box. 



411 seel laneous options= 



Printer output 

■Qi iiiMUMaziimsai ■■■j^rnrniFTCaaiM 



XJ Use expanded memory 
^ NMI Intercept 

Ignore case of symbols 



TOS shell swap size (Kb) 



Remote link port 



Link speed 




You can select another 

button with Tab; press Enter to 

choose that button. 



Check boxes and 
radio buttons 



This dialog box has three standard buttons: OK, Cancel, and Help. 
If you choose OK, the choices in the dialog box are recorded in 
Turbo Profiler; if you choose Cancel, nothing changes and no 
action is made, but the dialog box is put away. Choose Help to 
open a Help window about this dialog box. Esc is always a 
keyboard shortcut for Cancel (even if no Cancel button appears). 

If you're using a mouse, just click the button on the item you 
want. If you're using the keyboard, press Tab or Shift-Tab to move 
from section to section; each section highlights when it becomes 
the active one. 

Note that the OK button has a special look. It has a special color 
(in monochrome systems, arrows point to it ^like this*-). This 
indicates that OK is the default button, which means you need only 
press Enter to choose that button. Be aware that tabbing to a button 
makes that button the default. 

To choose a button with a mouse, cHck it. From the keyboard, you 
choose a button by pressing Tab untU the button is highlighted, 
and then pressing Enter. (Once you've tabbed past the buttons, 
pressing £/]ter chooses only the preset default button.) You can 
also press the highlighted letter associated with the button (/("for 
OK). 

The dialog box also has check boxes. When you select a check box, 
an X appears in it to show that it's on; an empty box indicates ifs 
off. To check a check box (set it to on), click it or its text, press Tab 
until the check box is highlighted and then press Spacebar, or press 
Alt and the highlighted letter. You can have any number of the 
check boxes checked at any time. 

If several check boxes apply to a topic, they appear as a group. 
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o 



Radio buttons are so called 

because tt)ey act Just like the 

group of buttons on a car 

radio. There is always one— 

and only one— button 

pushed In at a time. 



On monochrome monitors. Turbo Profiler indicates the active 
check box by placing a chevron symbol (») next to it. When you 
press Tab, the chevron moves to the next check box. 

The dialog box also has radio buttons. Radio buttons differ from 
check boxes in that they present mutually exclusive choices. For 
this reason, radio buttons always come in groups, and only one 
radio button can be on in any one group at any one time. 

To choose a radio button, click it or its text. From the keyboard, 
press Tab until the group is highlighted, then use the arrow keys 
to choose a particular radio button. Press Tab (or Shift-Tab) again to 
leave the group with the new radio button chosen. 

Here's what check boxes and radio buttons look like on and off: 



— Check boxes 

[ 1 Options 
m Layout 
[X] Macros 



Radio buttons 



None 

Iirmediate Callers 

All Callers 



Input boxes and lists 



Dialog boxes can also contain input boxes. These boxes allow you 
to type in text. All the regular text-editing keys work in the input 
box (for example, arrow keys. Home, and End). If you continue to 
type once you reach the end of the box, the contents automatically 
scroll. If there's more text than what shows in the box, arrowheads 
appear at the end (< and ►). You can click the arrowheads to scroll 
or drag the text. 

If an input box has a Q icon to its right, there is a history list 
associated with that input box. This history list lists the text you 
typed into this box the last few times you used this dialog. The 
Search box, for example, has a such a history list, which keeps 
track of the text you searched for previously. 

If you want to reenter text that you already entered, press i or 
click the Q icon. Y ou can edit an entry in the history list directly. 
Press Esc to remove the history list without making a selection. 

Here is what a history list for the FUe Name input box might look 
like if you had already used it four times: 
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Figure 4.3 
The File Name history ilst 
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Many dialog boxes also have a list box. You use a list box to scroll 
through long lists without leaving the dialog box. Turbo Profiler 
typically uses list boxes to display file names in dialog boxes. 

To display a list box, you click it, or press Tab until it's highlighted 
and then press Enter. To move through the list once the list box is 
displayed, you can use the scroll box or press T or i from the 
keyboard. 



Part 2: The menu reference 



This section gives you an item-by-item description of each menu 
command and dialog box option in the Turbo Profiler 
environment. The figure on page 72 is a ''road map" to the 
profiler's global menus (the menus that are called from the menu 
bar). 



= menu (System) 



Repaint desktop 
Restore standard 



About... 



The s menu (called the System menu) appears on the far left of the 
menu bar. To activate the = menu, either (1) press Alt Spacebar, or 
(2) press F10, then use -> or <- to go to the = symbol and press 
Enter. 

With the commands in the = menu, you can 

B repaint the screen 

B restore your original window configuration 

B activate a Turbo Profiler information box 
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Figure 4.4: Turbo Profiler's menu bar and global menus 
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■ (System) 



Repaint desktop 
Restore standard 



About... 



File 



Open... 
Change dir... 
Get info... 
DOS shell 
Quit Alt-X 



Run 



Run 

Progran reset 

Argunents 



F9 
Ctrl-F2 



Statistics 



Callers Enabled 

Files Enabled 

Interrupts Enabled 

Overlays Disabled 



Profiling options... 
Accunulatlon Enabled 

Delete all 



Save... 
Restore.. 



View 



Module 

Execution Profile 

Callers 

Overlays 

Interrupts 

Files 

Areas 

Routines 

Disassembly 



F3 



Options 



Macros 

Display options... 
Path for source... 
Save options... 
Restore options... 



Create... 


Alt - 


Stop recording 


Alt - 


Remove 




Delete all 





Window 



Zoom F5 

Next F6 

Next pane Tab 

Size/move Ctrl-F5 
Iconize/restore 

Close A1t-F3 

Undo close Alt-F6 



User screen Alt-F5 

1 Module PRIHEO 

2 Profile 



Print 



Statistics 
Module... 



Options... 



Help 



Index Shift-Fl 

Previous topic Alt-Fl 
Help on help 
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Repaint Desktop 



Choose Repaint Desktop when you want Turbo Profiler to redraw 
the screen. You might need to do this, for example, if a memory- 
resident program has left stray characters on the screen, or 
possibly if you have display swapping turned off. 



Restore Standard 



When you start up Turbo Profiler, it sets the environment 
windows' size, status (open or dosed), and placement according 
to information stored in the configuration file, TFCONFIG.TF. 
Once Turbo Profiler is onscreen, you can move and resize the 
windows, close some and open others, and generally make a real 
mess of your screen. The Restore Standard command provides a 
quick way to rectify such a situation. 

When you choose Restore Standard, Turbo Profiler puts all the 
windows back the way they were when you first started up the 
profiler. 



About When you choose About from the = menu, the About box pops 
up. This box Usts the Turbo Profiler version number and other 
interesting facts. Press Enter or choose OK to close the box. 



File menu 



Open... 
Change Dlr... 
Get Info... 
DOS Shell 
Quit Alt-X 



The File menu contains commands for 

a opening and loading a program to be profiled 

o changing the current directory 

a obtaining information about your program and system memory 
allocation 

a shelling out to the operating system 

D quitting the profiler 



Open The File I Open command opens the Program Load dialog box, 
shown here: 
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Figure 4.5 

The Program Load dialog 

box 




caiitest.exe 

doyt1nie.exe 

d1ce.exe 

insta11.exe 

nap.exe 

nodl.exe 

ovrdenn.exe 

pl.exe 

p2.exe 

p3.exe 

p4.exe 

D5.exe 
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With this dialog box, you can do any of the following: 

■ load an explicit file into the Module window 

■ use wildcards to filter the file list to match your specifications 

■ choose a file from a history Hst of previously-entered file names 

■ view the contents of different directories or drives 

There are three ways to load a file from this dialog box: 

1. Type in the file name, then choose OK (or press Enter). 

2. Press Enter or Tab to activate the files list box. Select (highlight) 
the file name you want, then choose OK or press Enter. 

3. Double-click the file name. 

You'U get an error message if you attempt to load a non-existent 
file or a file that isn't an .EXE file or that doesn't have debug 
information. 

Choose Cancel to leave the Program Load dialog box without 
loading a file. 

Using the File Name Input box 

When the File Name input box is active (the cursor is blinking in 
the box), you can do any of the following: 

■ Load an explicit file: Type in a full executable file name 
(including disk drive and relative or absolute path, if you want; 
you don't have to type the extension). Then choose OK (or 
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A history list shows the last 

eight file names you've 

entered. 



press Enter) to load that executable file's main source file into the 
Module window. 

B Filter the file list: Type in a file name (including disk drive and 
relative or absolute path) with DOS wildcards (? and *). Then 
move to the Files list box of matching file names to choose the 
file you want, or to the Directory list box to change to a 
different directory. 

B Choose from a history list: Press i to make a history list drop 
down below the Name input box. To choose a file from the 
history list, double-click the file name, or select it with an arrow 
key and press Enter. 



Using the Files list box 

By default, the Files list box displays all file names in the current 
directory that match the specifications in the Name input box as 
well as the names of directories you can move to from the current 
directory. If the Name input box specification includes a drive or 
path name, the list box displays all matching file names in the 
specified drive and directory. 

To load a file from the Files Hst box, 

1. CUck the list box (or press Tab until the list box name is 
highlighted). 

2. When the name is highHghted, either press i or T to select a 
file name (then press Enter), or double-click the file name. 

You can scroll the list box, if necessary, to see all the file names. 

If the file you want is in another directory, tab to the Directories 
list box and select the directory you want to move into. (To access 
the parent directory of the one you are currently in, type . . \ * . exe 
and press Enter. 

If you need to load your program with some command-line 
arguments, refer to the description of the Run I Arguments input 
box on page 110. 

Change Dir The File I Change Dir command brings up the New Directory 
dialog box. 
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Figure 4.6 

The New Directory dialog 

box 
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From this dialog box, you can log to a different current directory. 
(The current directory is where Turbo Profiler saves and looks for 
fQes.) 



New Directory dialog ix>x components 

You'll get an error message if The New Directory dialog box contains an input box in which you 
the new directory c^pj^be ^^ ^-^^ ^^^-^ ^^ ^^^ directory you want to access. When you have 

done so, choose OK to change directories, or Cancel to remain in 
your present one. 



Get Info 



Figure 4.7 
The Get Info text box 



The File I Get Info command displays a text box with information 
about the program being profiled and your system's current 
memory configuration. 



Program: C:\TPR0FILE\PRIHE1.EXE 
Status : Loaded 
Hode: Active 
Collection: Enabled 

Memory 

DOS : 226Kb 

Profiler : 282Kb 
Symbols : 8Kb 
Program : 196Kb 
Available: 0Kb 

____ Que _^^ 

DOS : 112Kb 

Profiler : 240Kb 
Program : 0Kb 
Available: 32Kb 

DOS version: 3.20 

6-14-1989 5: Z7pn 

OK ■ 



The information in the Get Info box is for display only; you can't 
change any settings from this box. Here's what the categories in 
this information box represent: 

■ Program is the program being profiled; you determine which 
file to profile with the File I Open command. 

■ Status is the reason why Turbo Profile gained control: it can be 
any one of these loaded messages: 
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No program loaded 
Control-Break 
Terminated, exit code XX 
Stopped by area 
NMI Interrupt 
Exception XX 
Divide by zero 

■ Mode is the profiling mode (active or passive); you specify the 
profiling mode with the Profile Mode radio button in the 
Profiling Options dialog box (accessed by choosing Statistics I 
Profiling Cations). 

■ Collection tells whether automatic data collection is enabled or 
disabled; you specify the data-collection setting with the 
Statistics I Accumulation command. 

■ Memory tells 

o DOS: Memory occupied by DOS and/or various device 
drivers. 

• Profiler: Total memory used by the profiler. 

o S5mibols: Memory allocated for the program's symbol table. 

o Program: Memory allocated to the current program being 
profiled. 

• Available: Amount of remaining available memory. 

■ EMS shows use of expanded memory by DOS, Turbo Profiler, 
the program's symbol table, the program being profiled, and 
available memory, like the base memory display. EMS appears 
only if expanded memory is present. 

■ DOS version shows the current DOS version on your system. 

■ Current date and time shows today's date and the time of day. 

After reviewing the information in the Get Info box, click OK or 
press Enter to return to the current window. 

DOS Shell The File I DOS Shell command steps you out of Turbo Profiler and 
back to the DOS prompt, so you can enter a DOS command or 
program. 

To return to Turbo Profiler, type exit at the DOS prompt. 

C^ In remote profiling mode, the DOS command line appears on the 
Turbo Profiler screen rather than on the User screen; this allows 
you to switch to DOS without disturbing your program's output. 
Because your program's output is always available on one 
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Quit 



monitor in the system. Window I User Screen and Alt-F5 are 
disabled. (See Appendix C for details about remote profiling.) 

The File I Quit command exits Turbo Profiler, removes it from 
memory, and returns to the DOS command line. Each time you 
exit Turbo Profiler, it remembers the areas you set up for the 
current program. 

If you have any profile data or setup parameters that you want to 
keep (such as the profile statistics, profiling and display options, 
and screen layout options), save them with Statistics I Save and 
Options I Save before exiting. Otherwise, you wUl lose the options 
you've set. 



View menu 



Table 4.2 

Summary of Turbo Profiler 

windows 



Module... F3 

Execution Profile 

Callers 

Overl ays 

Interrupts 

Files 

Areas 

Routines 

Disassembly 



The View menu lets you open several kinds of windows in which 
you can examine information about your program's performance. 



Window name 



What this window displays 



Module 
Execution Profile 

Callers 

Overlays 

Interrupts 

Files 
Areas 

Routines 
Disassembly (CPU) 



Source code for the program being profiled 

Statistical information about a program after 
the program has rim 

Information about how often a routine is called 
and which routines call it 

Information about overlays for Turbo Pascal, 
Turbo C, and Turbo Assembler 

Information about interrupt calls made by the 
program 

Information about file activity 

Detailed information about data-collection 
activities at the places marked in your source 
code 

All routines that can be used as profile area 
markers 

The current profile area in the Module window, 
as disassembled source code 



78 



Turbo Profiler User's Guide 



Module 



Figure 4.8 
The Module window 



When you choose Module, a dialog box appears in which you 
type the name of the module you want to open. Press OK to 
display this module in the Module window. The Module window 
displays source code for the program being profiled. In the 
Module window, you can exanune code and set areas to be 
profiled. Special hot keys and window links connect the code in 
this window to data and statistics in the other windows. 



p[i]=Hodule: PRIHEO File: primeO.c (modified) 7= 



/* Copyright (c) 1990, Borland International */ 

I* Program for generating prime numbers using Euclid's method •/ 

int primes [1000]; 
Idefine HAXPRIHES 1000 

* mainO 

int j: 

int lastprime, curprine; 

* primes [0] - 2 
'> priroes[l] - 3 
■► lastprime - 1 
>► curprirae - 3 



=[*]^ 



printf("prime \d - %d\n", 0, primesTO] 
printfrprime *d - *d\n", 1, primes[lj 
Nh11e(curprime < MAXPRIMES) 

for{j - 0; j <- lastprinie: j++) 



When you run the profiler, you'll need hoih. the .EXE file and the 
original source file available. Turbo Profiler looks for your 
program's source code in these places, in this order: 

1. In the directory where the program was originally compiled 

2. In the directories (if any) you've listed under Options I Path for 
Source 

3. In the current directory 

4. In the directory that contains the program you're profiling 

(The name of the directory where the program was originally 
compiled is contained in .EXE and .OBJ files ff you compiled your 
program with symbolic debugging information turned on.) 
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Line... 
Search... 
Next 
Goto... 



Add areas ► 
Renwve areas ► 
Operation... 
Callers... 



Module... 

File... 

Edit 



Press Alt-FlO or click the right mouse button to bring up the 
Module window's local menu. With the local menu commands, 
you can perform these actions: 

■ move the cursor to a specific line or code label 

■ search for text in the source code 

■ add and remove profile areas 

■ set the profiling action that will occur for a given area 

■ specify the level of call-path recording for a given routine 

■ load another module or another source file of the current 
module into the Module window 

■ invoke the editor of your choice 

To activate a local menu item directly (without bringing up the 
menu), press the Ctrl-(letter) hot key, where letter is the menu item's 
highUghted letter. 



CtfrUn Une 



To move swiftly to a particular line of code in the Module 
window, choose Line from the local menu. The dialog box that 
pops up requests the line number you seek; type in the new line 
number to go to, then choose OK (or press Entei). If you enter a 
line number after the last line in the file, you will be positioned at 
the last line in the file. 



Ctrl S Search 



To search for a character string in the current module, choose 
Search from the Module window's local menu. The prompt box 
that pops up requests the string to search for; type in the string, 
then choose OK (or press Enter). 

If the cursor is positioned over text that looks like a variable 
name, the prompt box comes up initialized to that name. If you 
mark a block in the file, the profiler uses that block to initialize the 
search prompt. This saves you from extraneous typing if the text 
you want to search for is a string already in the Module window. 

You can use the standard DOS wildcards (? and *): The ? indicates 
a match on any single character, and * matches or more 
characters. 
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The search does not wrap around from the end of the file to the 
beginning. To search the entire file, start at the first line. 



"CtrTirNl Next 



Once you've defined a search string with the Module window's 
local Search command, you can search for successive occurrences 
of that string with the Next command. Choose Next from the local 
menu, or press the shortcut, Ctrl-N. You can only use Next after 
issuing a Search command. 



"CtrTlfG] Goto 



Use the hex format of 

whichever language your 

program 's In. 



W}[A\ 



All routines 
Modules with source 
Routines In module 
Every line in nwdule 
Lines in routine 
Current routine Alt-F2 
This line F2 



To position the Module window's cursor on a particular routine or 
other code label in your program's source code, choose Goto. The 
prompt box that pops up requests the address you want to 
examine. Type in a line number, a routine name, or a hex address, 
then choose OK (or press Enter). 

For information on address syntax, see the chapter "Expressions" 
in the Turbo Debugger User's Guide. 

Add Areas 

Add Areas on the Module window's local menu leads to the menu 
shown here. 

a All Areas adds area markers for aU routines in the program 
being profiled, including routines for which source code is 
unavailable (such as Ubrary routines linked in as object 
modules from library files). 

m Modules with Source adds area markers for all routines in 
modules whose source code is available. 

a Routines in Module adds area markers for all routines in the 
current module (the one in the Module window). 

□ Every Line in Module adds area nnarkers for all lines in the 
current module. 

la Lines in Routine adds area markers for aU lines in the current 
routine (whichever routine the cursor is on in the Module 
window). 

■a Current Routine adds an area marker for whichever routine the 
cursor is on in the Module window. 
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I This Line adds an area marker for the line the cursor is on in the 
Module window. 



CtiTirRl Remove Areas 



All areas 

Modules with source 
Routines In module 
Every line in module 
Lines in routine 
Current routine Alt-F2 
This line F2 



Remove Areas on the Module window's local menu leads to the 
menu shown here. 

■ All Areas removes area markers for all routines in the program 
being profiled, including routines for which source code is 
unavailable (such as library routines linked in as object 
modules from libraiy files). 

■ Modules with Source removes area markers for all routines in 
modules whose source code is available. 

■ Routines in Module removes area markers for all routines in 
the current module (the one in the Module vdndow). 

■ Every Line in Module removes area markers for all lines in the 
current module. 

■ Lines in Routine removes area markers for all lines in the 
current routine (whichever routine the cursor is on in the 
Module window). 

■ Current Routine removes the area marker for whichever 
routine the cursor is on in the Module window. 

■ This Line removes the area marker for the line the cursor is on 
in the Module window. 



CtrTlfol Operation 



The Operation command opens the Area Options dialog box, 
which contains settings for the current area (the one where the 
cursor is in the Module window). 
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Figure 4.9 
The Area Options dialog box 



f!=["]===Area opti ons= =ti 


piillMJIHU^^ 


Kjperati oniwiM|||mnrfM^ 
11 ■} Noniial HBH|a (*) Separate WH 
m I ^^°P WM ( ) Connbined |S| 
M ) Enable RfflBRfflmffl^ii^ 

M\_> Disable mHoSlmmmmmm] 


W^^ 


^"■?;*'ii!mir^:' ■ iiarar^.'^- 


gm 


""I™"™" i^BM UBttj; 



You can specify two options from this dialog box: Operation and 
Timing. When you mark an area, a marker symbol signifying the 
chosen operation appears to the left of that area. 

D Operation specifies what profiling action will occur for the 
current area. 

Normal collects profile statistics for this area as specified in the 
Statistics menu (callers, file activity, interrupts, overlays, etc.) 
and Area Operations dialog box, which you reach through the 
local menus of the Module and Areas windows. 

Stop stops program execution at this marker. 

Enable turns on the collection of statistics at this point in the 
program. 

Disable temporarily turns off the collection of statistics at this 
point in the program. 

a Timing specifies whether the profiler will add the current area's 
execution time to a higher-level area or keep it separate. 

Separate adds any timer ticks occurring while program control 
is in the marked area to that area's timer-tick compartment only, 
not to the caUer's compartment. 

Combined adds timer ticks that occur while control is in the 
marked area to the area's timer-tick compartment and to the 
caUer's compartment. 

The Areas window displays operation and timer information for 
all marked areas. 



rciriirc] Callers 

The Callers command on the local menu leads to the Stack Trace 
dialog box. 



Chapter 4. The Turbo Profiler environment 



83 



Figure 4.10 
The Stack Trace dialog box 
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You can specify two options from this dialog box. Areas and 
Stack. 

■ Areas specifies which areas you want call paths recorded for. 

This Routine records call-path information for the current 
routine (the one the cursor is on in the Module window). 

This Module records call-path information for all marked 
routines in the current module (the one in the Module 
window). 

All Routines records call-path information for all routines in all 
modules in the program. 

■ Stack specifies how extensive ("deep") the recorded call stack 
should be. 

All Callers records all available call stack information for the 
routine(s) you've specified with the Areas option. 

Immediate Callers records only ''parent" information for the 
routine(s) youVe specified with the Areas option. 

None turns off call stack information for the routine(s) you've 
specified with the Areas option. 

Module 

The Module command on the local menu leads to the Pick a 
Module dialog box that lists aU your program's modules for 
which source is available. 
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Figure 4.11 

The Pick a IVlodule dialog 

box 
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Most modules only have a single source code file; other files 
included in a module (such as C header files) usually define only 
constants and data structures. Use this command to open a 
different module in the Module window. 

This option displays only modules for which source code exists, if 
they are associated with the program being profiled. It allows you 
to move rapidly from one module to another without having to 
search your source directory explicitly. 

The Module command searches for the source code in the 
following places, in the order listed: 

1. in the directory where the program was originally compiled 

2. in the directories (if any) youVe Usted under Options I Path for 
Source 

3. in the directory that contains the program you're profiling 

4. in the current directory 



fCtrnrFl File 



The File command on the local menu leads to a dialog box that 
lists all the source files used to compile the current module. Use 
this command if your module has source code in more than one 
file and the file you want is not displayed in the module window. 
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Figure 4.12 ii=["]=Pick a source fi1e=i 



ThG File dialog box 
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The File command searches for the source code in the following 
places, in the order listed: 

1. in the directory where the program was originally compiled 

2. in the directories (if any) youVe listed under Options I Path for 
Source 

3. in the directory that contains the program you're profiling 

4. in the current directory 



[CtrOd] Edit 



Although Turbo Profiler does not have a built-in editor, you can 
specify your own favorite editor as an option when you 
customize the profiler with the Turbo ProfQer installation 
program, TPTNST. See Appendix B for information about TFINST. 

Once youVe installed an editor via TFINST, whenever you choose 
Edit from the Module window's local menu. Turbo Profiler 
automatically shells out to DOS and invokes your editor. To 
return to the profiler from your editor, simply quit the editor. 



Execution Profile 



The Execution Profile window is where Turbo Profiler displays 
your program's profile statistics (after you've set areas and run the 
program under control of the profiler). 
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Figure 4.13 
The Execution Profile window 
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The Execution Profile window consists of one pane, divided into 
two display areas (top and bottom). The top display area lists 

II Total Time: your program's total execution time 

% of Total: how much of that total (a percentage) is represented 
by the statistics currently displayed in the bottom area of the 
window 

la Runs: the current profile run (if you're collecting and averaging 
statistics from more than one run) 

Q the options you've chosen from the local menu (display format, 
filter status, sort order) 

The bottom display area lists one or two lines of profile data for 
each area you've marked. The information shown in this display 
area can include each area's name or line number, the execution 
counts for each marked area, the time spent in each marked area, 
the average time per pass for each marked area, and the most time 
spent in a marked area on a single pass. 

If you have a Module window and an Execution Profile window 
onscreen at the same time, the Execution Profile window is 
positioned automatically to show the statistics for the area the 
cursor is on in the Module window. 
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Display... 
Filter 



All ► 



Hodule 
Remove 



To specify how the Execution Profile window displays your 
program's statistics, activate the local menu (press Alt-F10). 
Through this local menu, you can 

■ choose any one of five different ways to display profile statistics 
in the Execution Profile window 

■ sort the displayed statistics 

■ temporarily remove one or more areas' statistics from the 
display 

■ examine the source code for an area 

■ delete an area's statistics from memory 

To activate a local menu command directly (without bringing up 
the menu), press the Ctrl-(letter) hot key, where letter is the menu 
item's highlighted letter. 



"CtrTirDl Display 



Figure 4.14 

The Display Options dialog 

box 



When you choose Display from the Execution ProfQe window's 
local menu, this Display Options dialog box comes up. 




You can specify two options from this dialog box, Display and 
Sort. 

■ Display specifies what form the data will be displayed in. 

• Time displays the profQe statistics for each area as the time 
(in milliseconds) program control was in that area. 

• Counts displays profile statistics for each area as pass counts: 
how many times program control entered that area. 

• Both displays the statistics for each area as both time (the top 
hne) and coimts. This provides a graphic measure of a 
routine's efficiency. 

• Per CaU displays each area's statistics as the Time : Counts 
ratio. This provides the average time spent in each caU to the 
routine. 
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• Longest displays, for each area, the longest single time 
program control was in that area. 

Q Sort specifies what order the data will be sorted in. 

o Name sorts the profile statistics by area name, in 
alphanumeric order. 

e Address sorts profile statistics by memory location, starting 
with the lowest address. 

e Frequency sorts the statistics numerically, with the highest 
frequency at the top. 

The top display area of the Execution Profile window lists the 
current display and sort options. 



"CtrnfFl Filter 



All 

Module... 

Current 



The Filter command on the local menu leads to the three-item 
menu shown here. 

□ All restores all collected statistics for the current program to the 
Execution Profile window. 

After you've filtered out certain statistics from the Execution 
Profile window (with Filter I Module or Filter I Current), choose 
Filter I All to restore all profile statistics to the window. 

Q Module filters out all but one module's statistics. 

This command leads to the Pick a Module dialog box, which 
lists all modules for the current program. Use the T and i arrow 
keys to highlight one module in the list, then press Enter. Only 
the areas in the chosen module show up in the Execution 
Profile window. 

B Current temporarily removes the current routine's statistics 
from the Execution Profile window. 

Choose Filter I Current if you want to throw out one routine's 
statistics and see what happens to the remaining percentages. 
The Current command is a temporary filter that hides report 
information from sight without deleting any information; it 
does the following: 

1. Removes the current area's statistics from the Execution 
Profile window. 

2. Calculates original total execution time minus the time of 
the removed area. 
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3. Recalculates the remaining areas' percentages as fractions of 
the newly calculated total execution time. 

When you filter one or more areas' statistics from the Execution 
Profile window, the profiler calculates a new total execution time 
based on the statistics displayed in the window, but the Total 
Time value shown in the top of the window does not change. 

When you use Filter I Current, the original total execution time for 
the entire program remains displayed in the Execution Profile 
window's top display area. 

Don 't confuse Filter I Current Filter I Current is a temporary filter that hides report information 

"^^^ ^on!lTB^lt^i^'p°^^^^ ^^^^ '^s^*' "^^°^^ ^^^^^y ^^^^^^^ ^'^^ ^"^^' ^^^*^s^ ^y 

window's local menu, removing them in both the Module and Areas windows. 

fCtrniM] Module 

The Module command on the local menu takes you to the line of 
source code in the Module window for which the statistics are 
highlighted in the Execution Profile Window. 

For instance, suppose you highlight the statistics for routine f red 
in the Execution Profile window, then choose Module from the 
local menu to activate the Hnk. Turbo Profiler activates the 
Module window and places the cursor on the first line of f red in 
the source code. After that, you move the cursor to line 25 in the 
Module window (line 25 has an area marker). Automatically, the 
Execution Profile window's contents scroU so that the statistics for 
line 25 show at the top of the statistics display area. 

The link is one-directional: If you go back to the Execution Profile 
window (after going to the Module window) and move the 
highlight bar, the source code in the Module window does not 
scroll or track the highlight bar's position. (If it did, you could get 
very frustrated.) 

When you choose the Module conunand from the Execution 
Profile window's local menu, if source code for the highlighted 
line is unavailable, the link goes to the corresponding line of code 
in the Disassembly (CPU) window. This happens, for example, if 
you've marked areas for AU Routines and the highlighted line is a 
library routine. (See page 106 for details about the Disassembly 
window.) 
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Remove 

The Remove command removes area marker settings for the 
highlighted line from the Module and Areas windows. 

Attention! The Remove Once you remove the line's area markers with the Remove 
command erases statisiical command, the statistics you had gathered for that line are erased 
data. Use It with discretion. . ^ .• i.u j r x.i. 1. 1 • r j t- j 

and no more statistics are gathered for that Ime of code. To undo a 

Remove action, you must 

1. Activate the Module window and bring up its local menu. 

2. Place the cursor on the line whose marker you removed. 

3. Choose Add Areas I This line. 

4. Run the program again (collecting a new set of statistics). 



Callers 



Figure 4.15 

The Callers window, showing 

calls In CALLTEST 

An underscore precedes ttie 

Identifier names in this Callers 

window because Turbo C 

adds the underscore to all 

symbol names that appear In 

.OBJ files and In symbolic 

debugging Information. 



The Callers window is where Turbo Profiler displays the call 
paths for each marked routine in your program. You must set the 
Statistics I Callers menu item to Enabled before the profiler will 
record any call-path information. 

ij=[«l=Ca1 1 ers= 3 =[t] [;]= 



1 main 

77 'main b2 

33 main bl 

7700 main a b2 

33 main a bl 



The left pane in the Callers window lists each marked routine by 
name. When you highlight a routine name in the left pane, the 
right pane displays each tmique call path for that routine. If a call 
path is wider than the right pane, you can zoom the window or 
switch to the right pane and scroll left and right through the path. 

Although the CaUers window displays the call-path information, 
you specify what type of call-path recording you want through 
either the Module window or the Areas window. 

In the Module window, you can set callers options for whole 
groups of routines. 

1. With the cursor on a marked routine in the Module window, 
press M-F10 to bring up the local menu. 

2. Choose Callers to see the Stack Trace dialog box. 
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3. Set the Areas option. You can choose to record call paths for 
the current routine, all routines in the current module, or all 
routines in the program (including library routines). 

4. Set the Stack option. You can choose to record all callers for 
the chosen routine(s), immediate callers (the routines' parents, 
only), or no callers at all. 

5. Press Enter ot choose OK to go back to the Module window. 

In the Areas window, you can set callers options for individual 
marked routines. (See page 101 for more information about the 
Areas window.) 

1. In the Areas window, place the highlight bar on the routine 
you want to set call-path options for, then press M-F10 to bring 
up the local menu. 

2. Choose Options to see the Area Options dialog box. 

3. Set the Areas option. You can choose to record call paths for 
the current routine, aU routines in the current module, or all 
routines in the program (including Hbrary routines). 

4. Set the Callers option. You can choose to record all callers for 
the chosen routine(s), immediate callers (the routines' parents, 
only), or no caUers at aU. 

5. Press Enter or choose OK to go back to the Areas window. 

Figure 4.15 shows routine c highlighted in the left pane of the 
CaUers window, after a profile run of this program, CALLTEST: 

/* Program CALLTEST */ 

/* Copyright (c) 1990, Borland International */ 

{include <stdio.h> 

malnO 
{ 

o{); 

b2(); 

blO; 

a(); 
) 

a() 
{ 

int i; 

for (i = 0; i < 100; i++) 

b2(); 
bl(); 
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bio 
( 

int i; 

for (i = 0; i < 33; i++) 
o(); 



b2() 



int i; 



for (i 
o(); 

} 


= 0, 


i < 77; i++) 


c() 








t 
int 


i; 






for 


i = 


0; 


i < 3; i++) 



Figure 4.16 

The Callers window local 

menus 



} 

The Callers window's right pane lists each unique call path for 
routine c: 

D 1 call from main to c 
Q 7,700 calls from main to a to b2 to c 
m 33 calls from main to a to b1 to c 
m 33 calls from main to b1 to c 
o 77 calls from main to b2 to c 

You'll find the Callers window useful when you must make 
decisions about restructuring code, especially when if s possible to 
reach a routine through several different call paths. 

Both panes of the Callers window have local menus. In the Callers 
window's right pane, both local menu items bring up subsequent 
menus, as shown here: 



Left pane 
local menu 








= Pick a caller ==; 


Inosi mikn.. 




Hodule 








lUkdl IMCIIU 








Inspect 






Inspect - 




























Called 
Frequency 
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To activate the local menu from the current pane, press Alt-FIO. To 
alternate between the window's panes, press Tab. To activate a 
local menu item directly (without bringing up the menu), press 
the Ctrl-(letter) hot key, where letter is the menu item's highlighted 
letter. 



Ctrl irn Inspect (In left pane) 



When the highUght bar is on a routine name in the left pane, 
choose Inspect (or press its shortcut, Ctrl-l) to view the source code 
for that routine in the Module window. 



Ctrl i rn Inspect (In right pane) 



Figure 4.17 
The Pick a Caller dialog box 



When the highlight bar is on a call path in the right pane of the 
Callers window, you can "inspect" (view information about) 
elements in that call path in one of three other windows. 

1. Choose Inspect to bring up a Hst of those other windows. 

2. Choose the window you're interested in (Areas, Module, or 
Profile) from the hst. This brings up the Pick a Caller dialog 
box, which lists all callers on the current caU path. 

[p[i] P ick a calle r 



I main 



ETESBsrcaiT 



In the dialog box, highlight the caUer in question (use the 
arrow keys or a mouse click), then choose OK or press Enter. If 
the window you choose to inspect in isn't already open, the 
profiler opens it automatically, then goes to the caUer's location 
in that window. 



Ctr S 



Sort (in rigtit pane) 

With the local Sort command in the Callers window's right pane, 
you can sort the list of call paths in two ways: 

■ Called sorts the call paths in the same order that program 
control traversed them at run time. 

■ Frequency sorts the call paths by how often program control 
traversed each path, v^th the most-used path at the top of the 
Hst. 
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Overlays 



Figure 4.18 
The Overlays window 



The Overlays window is where Turbo Profiler displays 
information about overlay activity for Turbo Pascal, Turbo C, and 
Turbo Assembler programs. You must set the Statistics I Overlays 
menu item to Enabled before the profiler will record any overlay 
information. 



FW=0ver1ays — 3^[t] [*]=ti 


*TotaiftTinie:lBl'r6475?.secr?Di splay:!! CountWSM'«sa!y?1ffl 




OVRDEHOl ( 49 bytes) 40 | ||l|||||||||||||||||||||||||||||||||||||||| 


ISBiWIMiilltill^lBli^^ 


^■^^^H^ffl^^ffll^^^^^^^^^^^w^i^^^r-^ 



Dlsple^ 
Inspect 



Count 



The information hsted in this window can include 

a how many times your program loads each overlay into memory 

D how long it takes to load each overlay 

D the sequence in which your program loads the overlays 

□ the size of the overlap 

Like the Execution Profile window, the Overlays window is 
divided into two display areas, top and bottom. The top display 
area lists total execution time for your program and the current 
display option for overlay statistics. The bottom display area lists 
the overlay statistics as either a histogram or a list of events. 

For a live demonstration of how the Overlays window works, 
load the Turbo Pascal demonstration program OVRDEMO into 
the profiler. Then set area markers for every line in the module 
OVRDEMO, enable Statistics I Overlays, and run the program. 
(You'll need the files OVRDEMO.PAS, OVRDEMOl.PAS, 
0VRDEM02.PAS, and OVRDEMO.EXE to profile this program.) 

The Overlays window's local menu provides two commands, 
shown here. To activate the local menu from the Overlays 
window, press Ctrl-F10. To activate a local menu item directly 
(without bringing up the menu), press the Ctrl-(letter) hot key, 
where letter is the menu item's highlighted letter. 



"CtrTirD] Display 



Display specifies how the data will appear; you toggle between 
Count and History by pressing Enter. 
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Interrupts 



Figure 4,19 
The Interrupts window 



Count produces a histogram that shows, for each overlay, how 
much memory that overlay consumes and how many times your 
program loaded the overlay into memory. 

History hsts your program's overlay activity as a sequence of 
events; each line names the overlay and specifies when, in the 
course of program events, that overlay was loaded. 



CirTHTI Inspect 



Inspect goes automatically to the Module window (opening it, if 
necessary) and places the cursor on the source code for the 
highlighted overlay. 

The Interrupts window is where Turbo Profiler displays 
information about the video, disk, keyboard, DOS, and mouse 
interrupt events in your program. The Statistics I Interrupts menu 
item must be Enabled before the profiler will record any 
interrupt-caH information. 



fj=["]=Interrupts= 
lOH Video 



16H Keyboard 
21H DOS 



=3=rtim= 



Collection enabled 
Subf unctions enabled 
Display: Calls 
62 calls. 0.9876 sec 



UlBMWfflBmMMSM 



INT 10H/02H 
INT 10H/06H 
INT 10H/08H 
INT lOH/OFH 



The Interrupts window is divided into three panes: top left, top 
right, and bottom. 

■ The top left pane displays the specific interrupts caUed by your 
program (by INT number and name). 

■ The top right pane hsts information about the display mode 
and the current interrupt (the one highlighted in the top left 
pane), number of calls, and execution time. You cannot tab to 
the top right pane; it only displays information. 

■ In the bottom pane, you see a profile of data for each interrupt, 
shown as a histogram or as start time and duration. 

Both active panes of the Interrupts window have local menus. 
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Figure 4.20 

The Interrupt \A/indow local 

menus 



Top left pane 
local menu 






Sottoni pane 
oca1 nenu 




Collection 
Subroutines 


























Add... 
Pick... 
Rennve 
Delete all 








Time 

Calls 

Both Time and Calls 






Events 



To activate the local menu from the current pane, press Alt-FIO. To 
alternate between the window's panes, press Tab. To activate a 
local menu item directly (without bringing up the menu), press 
the Ctrl-(letter) hot key, where letter is the menu item's highlighted 
letter. 

Each entry in the bottom pane of the Interrupt window can list 

□ the interrupt by name or INT number (or both) 

□ the number of caUs to that interrupt (as an absolute number and 
as a percentage) 

□ the total amount of execution time spent in that interrupt (as an 
absolute number and as a percentage) 



Ctrl 



CJ Collection (in top pane) 

The Collection command enables or disables collection of statistics 
for the current interrupt (the one highlighted in the left display 
area of the top pane). 



Ctrl 



^ Subroutines (in top pane) 

The Subroutines command enables or disables collection of 
statistics for subroutines of the current interrupt (particularly 
useful for DOS INT 21H calls). Subroutine numbers are 
determined from the value in the AH register when the interrupt 
is called. 



CtrTllAl 



Add (in top pane) 

The Add command adds an interrupt, by number, to the list in the 
pane's left display area. (You type in the DSfT number in decimal 
notation: 33, not 21H.) 
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"CtrnfP 



Pick (in top pane) 

The Pick command displays a predetermined list of interrupts, so 
you can pick one to add to the list in the left display area. 



[ Ctrl Ifnl Remove (in top pane) 



The Remove command removes the current highlighted interrupt 
from the list in the pane's left display area. 



"CtrFinDl Delete All (in top pane) 



The Delete All command removes all the listed interrupts in the 
pane's left display area. 



Ctrl D Display (In bottom pane) 



The Interrupt window's bottom pane has a one-item local menu; 
its command. Display, leads to a subsequent menu. From this 
second menu, you can choose to display interrupt statistics in one 
of four different formats: 



Time 
Calls 

Both Time and Calls 
Events 



Displays the amount of time spent in 
each interrupt and its subfunctions. 

Displays the number of times each 
interrupt and its subfunctions were 
called. 

Displays both the amount of time and 
the number of times that each 
interrupt and its subfunctions were 
called. 

Displays a time ordered list of 
interrupt calls. 



Files The Files window is where Turbo Profiler displays information 
about fQe activity that occurred during your program's run. 
Statistics I Files must be set to Enabled (the default), so the profiler 
will record any file-activity information, such as read, write, open, 
or close. 
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Figure 4.21 
ThG Files window 



=W=Files= 



=3=rtl ril=ii 



Handle b 

Opened at 0.1224 sec for ??? 

Open took 0.0235 sec 

161 reads, 4566 bytes. 0.0642 -.sec 

writes, bytes, sec 



Open 5 0.0235 sec 
Read 5 0.0199 sec 
Read 6 0.0002 sec 



Figure 4.22 
The Files window local menus 



The Files window is divided into three panes: top left, top right, 
and bottom. 

The top left pane lists files by name, including STDIN and 
STDOUT. As you move the highlight bar over the file name 
you're interested in, the top right pane shows, for that file, 

B the handle number 

D the time when the file was opened 

D how long the file was open 

D the number of reads and writes from and to the file 

n the total number of bytes read and written 

□ the time for all reads from and writes to the file 

D the time required to close the file 

The top right pane only displays information. You can't tab to it, 
and it does not have a local menu. 

The lower pane displays file activity statistics (reads, writes, 
opens, and closes) as individual entries, rather than as statistical 
totals associated with a single file-name entry. Each entry 
provides information about a given file activity. 

Both active panes of the Files window have local menus. 



Top left pane 
local menu 



Collection 
Detail 
When Full 



Bottom pane 
local menu 



Display 



To alternate between the window's panes, press Tab. To activate 
the current pane's local menu, press Ctrl-F10. To activate a local 
menu item directly (without bringing up the menu), press the 
Ctfl-(letter) hot key, where letter is the menu item's highlighted letter. 
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Ctr C 



Collection (in top pane) 

The Collection cominand enables or disables the collection of file 
activity statistics for the current file (the one highlighted in the left 
display area of the top pane). 

Each entry in the bottom pane of the Files window provides 
information about a given file activity. 



W][d] Detail (in top pane) 



The Detail command enables or disables a detailed Hsting of file- 
activity statistics. A detailed listing logs each file read and write 
activity separately, with the time from the program start the 
activity occurred and the number of bytes transferred. When 
Detail is disabled, only file open and close activities are logged 
individually; reads and writes are summarized. 



CtrTlfWl When Full (in top pane) 



The When Full command specifies what happens when the 
memory set aside for file-activity statistics fills up. 

Wrap means that the newest file-activity statistics will overwrite 
the oldest ones when the memory area fills up. 

Stop means that file-activity statistics gathering will stop when the 
memory area fills up. 



I Ctrl IfPl Display (in bottom pane) 



In the Files window's bottom pane, you can choose one menu 
item. Display, which leads to the Display Options dialog box, 
shown here. 
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Figure 4.23 

The Display Options dlaiog 

box 
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p 
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You can specify two options from this dialog box: Display and 
Sort. 

a Display specifies how you want file-activity statistics to appear 
in the bottom pane. 

Graph displays each activity's total time as a bar graph. 

Detail displays each activity's exact time in seconds. 

m Sort specifies the order in which Turbo Profiler sorts the 
displayed statistics. 

Start Time sorts the files' statistics by sequential order of 
occurrence. 

Duration sorts the files' statistics by how long the open, read, 
write, or close operation took. 



Areas 



Figure 4.24 
The Areas window 



The Areas window is where Turbo Profiler displays detailed 
information about your program's marked profile areas. Use it to 
verify that the point and shoot Add /Remove Areas commands in 
the Module window local menu have set or cleared the desired 
area, and to adjust the behavior of individual areas. 

ri=ri]=Areas 3=m [i]=n 



; Name; i; f 3" ■ ' r • :■ Start Length :i CI ock ; Acti on - Cal 1 erst 
0VRDEMOi;45 ; * 7eb6:0044: 002a (Separate Normal V Stack £: 
0VRDEM0.46 - ;7eb6:006e: 0008 SeparateVNorinal ; Stacks 



OVRDEH0.50.: 7eb6:007b 0005*Separate Normal . Stack ; 
0VRDEH0.51 7eb6:00a0 0009 Separate Normal Stack I 
0VRDEM0,52 7eb6:0089 000a Separate Normal Stack 



The file name appears only if 

tt)e module is made up of 

more than one file. 



By default, the Areas window lists each area in alphabetical order. 
For typical programs, these areas are designated by the names of 
the routines to which they correspond. However, if you mark 
each Hne in a routine, the area name is (generically) 



ModName . FileName . 



where ModName is the module name, FileName is the file name, 
and NN is the Hne number. If you mark a line associated with a 
label (for example, a routine name), the profiler uses the label as 
the area name. 
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Add areas 
Remove areas 
Inspect 



Options... 

Sort Name ► 



The Areas window shows the following information associated 
with each marked area: 

■ Start: starting address in hexadecimal 

■ Length: length in bytes, as a hexadecimal number 

■ Clock: whether the area uses a separate or combined clock in 
timing descendent areas 

■ Action: the area operation (what Turbo Profiler should do when 
it enters or leaves that area) 

■ Callers: whether the profiler tracks the area's iirunediate caller 
only, all callers, or no callers 

The Areas window is more than a source window for static 
display of information. With the local menu, you can 

■ add or remove areas 

■ inspect areas 

■ change options for individual areas 

■ sort the displayed information 

To activate the window's local menu, press Alt-F10. To activate a 
local menu item directly (without bringing up the menu), press 
the Ctrl-(letter) hot key, where letter is the menu item's highlighted 
letter. 



rctriirA] Add Areas 



Choose Add Areas to specify all routines in your module as a 
specific routine or module that you want marked as an area. This 
command resembles the Module window's local Add Areas 
command. 



Ctr R 



Remove Areas 

The Remove command removes all information displayed for an 
area and removes that area's markers. 



Ctriirn Inspect 



When you choose Inspect, the profiler switches to the Module 
window and places the cursor on the first line of source code 
corresponding to the current area (the one highlighted in the 
Areas window). 
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Figure 4.25 
The Area Options dialog box 



Options 

When you choose Options from the Areas window's local menu, 
the Area Options dialog box comes up. 

r— Til ■ '■ , ■ , A ppa ontlons 




You can specify three options from this dialog box: Operation, 
CaUers, and Timing. 

D Operation specifies what profiling action wUl occur for the 
current area. 

Normal collects profile statistics for this area. 

Stop stops program execution at this marker. 

Enable turns on the collection of statistics at this area marker. 

Disable turns off the collection of statistics at this marker. Data 
collection resumes once program control passes an enabled 
marker. 

H Callers specifies which level of callers the profiler wOl track. 

All Callers records all available call-path information for the 
current routine. 

Immediate CaUers records only "parent" information for the 
current routine. 

None turns off call-path information for the current routine. 

B Timing specifies whether the profiler will add the current area's 
execution time to a higher-level area or keep it separate. 

Separate adds any timer ticks occurring while program control 
is in this marked area to the area's timer-tick compartment only, 
not to the caller's compartment. 

Combined adds timer ticks that occur while control is in this 
marked area to the area's timer-tick compartment and to the 
caller's compartment. You can specify combined time for an 
area only if that area's CaUers setting is Immediate or All. 
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Figure 4.26 
Propagation of time 



The following figure illustrates how time propagates from called 
routines to the calling routines when the caller's clock is set to 
Combined. 





main 


|-1— 1 Clock 
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In this figure, bl's clock is combined and bl calls c1, so cVs time is 
combined with b1's time. Part of el's time is actually dl's time, 
because el's clock is combined. 

Both bl and b2 call routine e2. 

■ Routine e2's time from when bl calls it — ^which includes all of 
d2's time — ^is combined with bl's time, because bl's clock is 
combined. 

■ But e2's time from when b2 calls it is not combined with b2's 
time, because b2's clock is separate. 



fCirlirsl Sort 

The Sort command rearranges the information displayed in the 
Areas window. You can sort alphabetically (by Name) or 
numerically (by Address). Sorting by Address Hsts the areas in an 
order more consistent with the order in which they appear in 
your source code. 

Routines The Routines window is where Turbo Profiler displays a list of all 
routines that you can use as area markers. Use it when you can't 
remember the name of a routine, or to see which routines have 
areas set on them. You can use the Inspect command to go to 
other modules by "inspecting" a routine in a particular module. 

This menu option gives you easy access to information related to 
a symbol. 
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Figure 4.27 
The Routines window 



Figure 4.28 

The Routines window iocoi 

menus 



The information displayed is basically a list of all global symbols 
available from debug information included in the executable file. 
These symbols include aU routine and procedure names in 
standard libraries for Turbo C and Turbo Pascal, as well as the 
names of routines in any third-party libraries you might be using 
(provided you link to those libraries with symbolic debug 
information turned on). 

lr=[«3=Routines , 3 =[t] [;]=n 

CRT.TEXTHODE 




The Routines window is divided into two panes, left and right. 
The left pane lists routines global to your whole profiled program, 
and the right pane lists routines that are local to the current 
module of the program you're profiling. 

Local routines include nested routines and procedures in Pascal 
and static routines in C. Global routines with source code 
available appear highlighted in the right pane. (By default, an 
underscore ( _ ) precedes all global variables in Turbo C 
programs.) 

Both panes of the Routines window have local menus. 



.eft pane 
local menu 




Right pane 
local menu 


Areas 
Callers 
Hodule 
Profile 






Local Hodule 


Areas 
Callers 
Hodule 
Profile 







To alternate between the window's panes, press Tab. To activate 
the current pane's local menu, press Alt-F10. To activate a local 
menu item directly (without bringing up the menu), press the 
Ctrl-(letter) hot key, where letter is the menu item's highlighted letter. 



Ctriirn Local Module (in right pane) 



When you choose Local Module in the Global Routines pane (the 
right pane), this Pick a Module dialog box pops up, listing all 
modiiles in your program. 
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Figure 4.29 

The Pick a Module diaiog 

box 



[■l=^1ck a nndulc 



All nndules 
PRIMEO 
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After you highlight a module and choose OK, the profiler 
displays that module's local symbols in the right pane of the 
Routines window. 



Ctrl A 



Areas (in both panes) 

The Areas command opens an Areas window and positions that 
window's highlight bar on the current routine (the one thaf s 
highUghted in the Routines window). 



I Ctrl I fc] Callers (in both panes) 



The Callers command opens a Callers window and shows the 
current routine's callers. 



Ctrl M 



Module (in both panes) 

The Module command opens a Module window and shows the 
source code for the current routine. 



Ctr S 



Profile (in both panes) 

The Profile command opens the Execution Profile window and 
shows the profile statistics for the current routine. 



Disassembly (CPU) 



The Disassembly window (labeled "CPU" when it's on the screen) 
displays the current area in the Module window as disassembled 
source code. You use the Disassembly (CPU) window to help 
determine if you want to rewrite parts of your program in 
assembly language. 
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Figure 4.30 

The Disassembly (CPU) 

window 



Goto... 
Origin 
Follow 
Previous 
View source 
Mixed Yes 



!!=[■] =CPU 80286== = 

0VRDEH0.49: Writel; 



=3=[t][;]=i, 



•»-7EB6:0076 9A2500C37E 

0VRDEH0.50: WriteZ; 

•»'7EB6:007B gA2500C07E call 

0VRDEH0.51: until KeyPressed; 

•»'7EB6:0080 9AFA02C67E call 

7EB6:0085 08C0 or 

7EB6:0087 74ED je 

0VRDEH0.52: end. 

■>-7EB6:0089 89EC n»v 

7EB6:008B 5D pop 

7EB6:008C 31C0 xor 



call far OVRDEHOl.WRITEl 



far 0VRDEf102.URITE2 

far CRT.KEYPRESSED 

al.al 

0VRDEH0.49 (0076) 

sp.bp 
bp 
ax, ax 



The left part of each disassembled line shows the instruction's 
address, either as a hexadecimal SegmentiOffset value or, if the 
segment value is the same as the current CS register, as a CS'.Offset 
value. If the window is wide enough (zoomed or resized), it also 
displays the bytes that make up the instruction. The disassembled 
instruction appears to the right of each line. 

In the Disassembly (CPU) window, global symbols appear simply 
as the symbol name. Static symbols appear (genericaUy) as 



ModName . SymbolName 
ModNamel SymbolName 



/* Turbo C */ 
( Turbo Pascal 



where ModName is the module name and SymbolName is the static 
s)nTibol name. Line numbers appear (also generically) as 



ModName .LineNumber 
ModNametLineNumber 



/* Turbo C V 
( Turbo Pascal } 



where ModName is the module name and LineNumber is the 
decimal line number. 

In the Disassembly (CPU) window, you can use the F2 function 
key to set area markers for each machine instruction you want to 
monitor. Any instructions marked in this fashion that have no 
symbol name appear in the Areas window as hex addresses in 
SegmentOjfset form. 

With the Disassembly (CPU) window's local menu commands, 
you can go immediately to any of these locations: 

B a specified address, to examine code 

D the current program location (CS:IP) 

HI the destination address of the current instruction 

■ the previous instruction pointer address 

D the address in the source code 
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You can also choose a local menu item to activate the Module 
window and move its cursor to the source for the current 
instruction, or to display disassembled instructions and source 
code three different ways. 

To activate the window's local menu, press Alt-F10. To activate a 
local menu item directly (without bringing up the menu), press 
the Ctrl-(letter) hot key, where letter is the menu item's highlighted 
letter. 



Ctrl G Goto 



Ctrl O 



When you choose Goto, a dialog box pops up and requests the 
address you want to go to. Enter a hexadecimal address, using the 
hex format of the language your program is in. 

You can enter addresses outside of your program to examine code 
in the BIOS ROM, inside DOS, and in resident utiKties. 

The Previous command restores the Disassembly (CPU) window 
to the position it had before you chose Goto. 

Origin 

You choose Origin to position the window's highlight bar at the 
current program location as indicated by the CS:IP register pair. 
This command is useful when you have been looking at your code 
and want to get back to the address of the current instruction 
pointer (CS:IP), where your program is stopped. 

The Previous command restores the Disassembly (CPU) window 
to the position it had before you chose Origin. 



[Ctrnin Foiiow 



The Follow command positions the Disassembly (CPU) window's 
highlight bar at the destination address of the currently 
highhghted instruction. The window scrolls to display the code at 
the address where the currently highhghted instruction will 
transfer control. For conditional jumps, the window shows the 
address as if the jump occurred. 

You can use this command with CALL, JMP, conditional jump 
(JZ, JNE, LOOP, JCXZ, etc.) and INT instructions. 
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The Previous command restores the Disassembly (CPU) window 
to the position it had before you chose Follow. 



"CtrnfFI Previous 



When you issue a command that changes the instruction pointer 
address (such as Goto, Origin, or FoUow), the Previous command 
goes back to the address displayed before you issued that 
address-changing command. If you move around with the arrow 
keys and the PgUp and PgDn keys, the profiler does not remember 
the window's position, but you can always return to the origin, 
which is the current CS:1P. 

Repeated use of the Previous command switches the Disassembly 
(CPU) window back and forth between two addresses. 



"CtrTirv] View Source 



The View Source coinmand opens a Module window and shows 
the source code for the current routine. 



"cirFlfMl Mixed 



There are three ways to display disassembled instructions and 
source code in the Disassembly (CPU) window. You choose the 
window's display format with the local menu's Mixed command, 
which toggles between three choices: No, Yes, and Both. 

n No means that no source code is displayed, only disassembled 
instructions. 

In No mode, global label names are still used in place of 
addresses for caUs, jumps, and references to data items. 

Q Yes means that source code lines appear before the first 
disassembled instruction for that source line. 

The profiler automatically sets the window to Yes if your 
current module is a high-level language source module. 

o Both means that source code lines replace disassembled lines for 
those Unes that have corresponding source code; otherwise, the 
disassembled instruction appears. 

TTie profiler sets the window to Both if your current module is 
an assembler source module. 
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Use Both if you're profiling an assembler module and want to 
see the original source code line, instead of the corresponding 
disassembled instruction. 



Run menu 



Run 

Program reset 

Arguments... 



F9 
Ctrl-F2 



^ 



Run 



Program Reset 
[ctFQ[l 



The Run menu provides three commands for running your 
program: Run, Program Reset, and Arguments. Control returns to 
the profiler when one of the following events occurs: 

■ Your program finishes running. 

■ Your program encoimters an area marker whose operation is 
Stop. 

■ You interrupt execution with the interrupt key. 

(Usually, the interrupt key is the Ctrl-Break key combination; you 
can change this to another key with TFINST, the profiler 
installation program. See Appendix B for details.) 

You can run your program even if the Module window is closed 
(as long as there's a program loaded into Turbo Profiler). 

When you choose Run I Rim or Run I Program Reset, any statistics 
collected for a previous execution are reset. If you want to save a 
set of statistics, use Statistics I Save before you run or reset. 

The Run command runs your program and collects performance 
statistics. 

If you set the Display Swapping option in the Display Options 
dialog box to Always, your program's output replaces the Turbo 
Profiler environment screen imtil the program finishes or you 
interrupt it. 

If you set Display Swapping to None, the Turbo Profiler 
environment stays onscreen while your program runs, but the 
word RUNNING appears in the upper right comer of the screen. 

The Run I Program Reset command reloads your program from 
disk. Use this command if you've run your program too far 
during a profiling session and need to restart execution at the 
start of the program. 

If you select Run 1 Program Reset when the Module or 
Disassembly (CPU) window is active, the display in that vmidow 
won't return to the start of the program. Instead, the cursor stays 
exactly where it was when you chose Program Reset. 
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Arguments The program you're profiling might expect command-line 

arguments. With Run I Arguments, you can store your program's 
command-line arguments within Turbo Profiler. Then, when you 
choose Run I Run or Run I Program Reset, the profiler passes the 
arguments to your program just as if you had typed them in at the 
command line. You can change these arguments from within 
Turbo Profiler and rerun your program. 

Enter the arguments exactly as you would at the DOS command 
line. (Do not enter the program name.) 



Statistics menu 



Callers 
Files 

Interrupts 
Overl ays 



Disabled 

Enabled 

Disabled 

Disabled 



Profiling Options... 
Accumulation Enabled 
Delete All 



Save... 
Restore. 



The Statistics menu contains commands to 

n specify the type of data the profiler will collect (callers, files, 

interrupts, overlays) 
a set the profile mode to active or passive 
D determine the number of program runs and areas 
□ turn automatic data collection on and off 
D erase profile statistics 
D save profile statistics to a file 
D restore previously saved statistics 

You can save all statistical information from the current profile to 
a .TFS file. Then, whenever you want to study the profile results, 
you can load that .TFS file — ^recovering all the saved statistics 
without having to rerun the profile. 

This feature is most useful if your programs take a long time to 
run or profile. You can save mtiltiple versions of profiles under 
different conditions, then restore each of the resulting profiles for 
quick comparison at a later date. Or, you can write a macro to 
automatically run five profiles with different options or area 
markers, then save the results in five different .TPS files. 

You can then run the macro overnight and come back to your 
results in the morning. 
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Callers 

You must run your program 

and accumulate some 

statistics before thiese 

windows st)ow any 

information. 



Files 



Interrupts 



When you enable the Callers option, the profiler gathers statistics 
about which routines caU other routines. To specify which 
routines you want call histories for, you choose the Callers 
command on the Module window's local menu or the Options 
command on the Areas window's local menu, then select the 
appropriate radio buttons under Callers and Areas. 

After running your program and gathering the profile 
information, use the Callers window to look at the call-history 
statistics. 

Gathering caller information consumes memory and slows down 
your program's run speed. If you don't need caller information, 
set Callers to Disabled. 

When you enable the Files option, the profiler gathers statistics 
about which files your program opens, and which read and write 
operations take place. 

After running your program and gathering the profile 
information, use the Files window to look at your program's file 
activity. 

Gathering file-activity information consumes memory and slows 
down your program's run speed. If you don't need file-activity 
information, set Files to Disabled. 

When you enable the Interrupts option, the profiler collects 
statistics about which interrupts your program calls. The profiler 
keeps separate statistics for DOS, Video, Disk BIOS and Keyboard 
interrupts. 

After running your program and gathering the profile 
information, use the Interrupts window to look at which 
interrupts your program called. 

Gathering interrupt information consumes memory and slows 
down your program's run speed. If you don't need interrupts 
information, set Interrupts to Disabled. 
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Overlays The Overlays option toggles whether statistics are collected for 
the overlays your program loads. 

If your program does not contain overlays, an error message is 
displayed and the option remains disabled. 

Gathering overlay information consumes memory and slows 
down the speed at which your program runs. If you don't need 
overlay information, you should disable this option. 

Profiling Options The Statistics I Profiling Options command opens the Profiling 
Options dialog box, shown here: 

FiaLirs4 31 r=ri1 Profiling ODtions= 

The Profiling Options diaiog 
box 




Clock speed 



M<riot aval iaDie> 



^ta-,: , ismK iiiaiir^ 



With the Profiling Options dialog box, you can set any of the 
following options: 

B Profile Mode specifies which type of analysis the profiler will 
perform. The default is Active. 

Active analysis means the profiler will collect full statistical 
information for each marked routine: basic clock timing 
information, how many times it was called, and which routines 
called it. 

Passive analysis means the profiler wiU only collect basic clock 
timing information for each marked routine. 

m Run Count sets how many times your program will run while 
the profiler collects statistics. The default is 1. 

H Maximum Areas specifies the maximum number of areas you 
can divide the current program into. The default is twice the 
number of routines in the program being profiled. 

D Clock Speed defines the speed of the timing clock, in ticks per 
second. The default is 100 ticks per second. Clock speed is 
available only in passive mode, not in active mode. 
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With the options in this dialog box, you can tailor the profiling 
session to meet your unique programming needs. 

Active analysis mode provides the most detailed analysis of your 
program at the cost of slowing program execution speed. On the 
other hand, passive mode allows your program to run at almost 
full speed, but does not provide any information about how many 
times a routine was called or which routines called it. 

If there are not many clock ticks during the time your profiled 
program runs, the data collected might not accurately reflect the 
time spent in various parts of the program. Running the program 
several times helps improve the accuracy by increasing the total 
number of data points collected. Speeding up the clock is another 
way to increase the total number of data points; this increases the 
accuracy of the timing statistics for each region at the expense of 
slowing down program execution speed. 

cj^ The profiler doesn't actually time each area, but uses the interrupt 
timer to increment a timer count. When the program terminates, 
the profiler converts the values in the timer counts to execution 
times, based on the current setting of the Clock Speed option in 
the Profiling Options dialog box. 

Accumulation The Statistics I Accumulation option turns automatic data 

collection on and off, which means you can (1) collect data for a 
subset of aU marked areas without removing any area markers 
and (2) manually turn data collection on after your program 
begins running. 

To collect data for a subset of aU marked areas, do this: 

1. In the Areas window's local menu, choose Options to open the 
Area Options dialog box. 

2. For those areas whose statistics you want, change the area 
marker from Normal to Enable (to start data collection) or to 
Disable (to stop data collection). 

3. Set Statistics I Accumulation to Disabled. 

4. Run your program. The profiler will not start collecting data 
until it trips an area marker that's set to Enable. 

To turn on data collection manually after your program has 
started running, do this: 

1. Set area markers. 
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2. Set Statistics I Accumulation to Disabled. 

3. Run your program from the profiler (press F9). 

4. When the program is in the appropriate run-time state, 
interrupt it. 

5. Enable the collection of profile data (set Statistics I 
Accumulation to Enabled). 

6. Resume program execution (press F9 again). 

Turbo Profiler starts accumulating statistics immediately for the 
marked areas. 

When you would disable accumulation 

Sometimes, when many different places in your program call a 
routine or family of routines, you want to know only the time 
spent in the routine, when a specific part of your code calls it or 
the time spent in the routine after a specific event. 

To monitor only certain calls to a routine, use Statistics I 
Accumulation to disable data-collection at the start. Mark an area 
that enables collection just before the call to the routine that you 
want to collect statistics for (set the area marker to Enable. Mark 
another area that disables collection after the routine returns. You 
can also set Enable and Disable areas in unrelated parts of the 
code; do this when you want to collect statistics only after a 
certain event. 

Example #1 : Collecting only for a specific call to a routine 

Suppose that you're only interested in calls to abc when it is 
called from xyz, but not at any other time. 

=> mainO /* normal area marker at routine */ 



abc(); /* don't want to collect statistics for this call 

*/ 

xyzO; 
} 

=> xyz() /* normal area marker at routine */ 

{ 

e> abc(); /* want to collect statistics for this call */ 
d> : 
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abcO 



/* normal area marker at routine */ 



Notice the e> that enables collection and the d> that disables 
collection. You must disable Statistics I Accumulation before 
running your program, or the profiler will erroneously collect 
statistics for the first call to abc in main. 

Example #2: Collecting after a certain event has occurred 

Suppose that routine xyz behaves differently depending on some 
global state information controlled by the two routines bufferon 
and bufferoff . You are only interested in the time spent in xyz 
when buffer flag equals 1. 



=> main ( ) 



/* normal area marker at routine */ 



xyzO; 
bufferon ; 
xyzO; 

bufferoff 0; 
xyzO; 



/* no statistics collected here */ 



/* will collect statistics for this call */ 



/* no statistics collected here */ 



=> bufferon ( ) 



/* normal area marker at routine */ 



bufferflag = 1; 



e> 1 

d> bufferoffO 



/* normal area marker at routine */ 



bufferflag = 0; 



=> xyzO 



/* normal area marker at routine */ 
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Notice that the e> to enable collection and the d> to disable 
collection are not near the calls to xyz. Once again, you must 
disable data-collection at the start (by setting Statistics I 
Accumulation to Disabled), or the first call to xyz will erroneously 
contribute to the collected statistics. 

Delete All The statistics I Delete All command erases all statistics collected 
for the current profiling session — essentially wiping the data slate 
clean so you can start afresh. Delete All removes all profile data 
from the open profile report windows (Execution Profile, Callers, 
Interrupts, Files, and Overlays), but it does not delete the profiling 
options you've set. 



Save 



Figure 4.32 
The Save dialog box 



The Statistics I Save command saves the following data, settings, 
and options: 

D all statistics for which collection was enabled when you ran the 
current profile (execution times and counts, callers, file activity, 
interrupts, overlays) 

a all area information (area names, operations, callers, separate 
versus combined timing) displayed in the Execution Profile 
window 

Once youVe saved statistics to a file, you can recover them at any 
time with the Statistics I Restore command. 

When you choose Statistics I Save, this dialog box comes up: 

E nter file name to save to = 



primeO.tfs 


directories 







Ok 



fMmr 



Hell 



G:\NETFILES\PEPPER\PR0GRAH\PR1HE0.TFS 
PRIMEO.TFS Jan 11. 1990 3:13pm 2174 bytes 



The Name input box lists a default .TPS file name (progname.TFSf 
where progname is the current program's name). 
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Saving Files 

To save the current profile statistics to the default file, choose OK. 

To save them to a different file, 

1. Activate the File I Name input box. 

2. Type in the different file name (including disk drive and path, 
if you so choose). 

3. Choose OK (or press Enter). 

If the .TFS file already exists, a message box asks if it's all right to 
overwrite the file. 

Restore When you choose Statistics I Restore, this dialog box comes up: 

Figure 4.33 !?=[■] ===^=Enter file name to res tore froro= 



The Restore dialog box 




pass.tfs 
pasG.tfs 
prime. tfs 
prImeO.tfs 
prlmeOa.tfs 
primeOpa.tfs 
priroel.tfs 
prime2.tfs 
primes. tfs 
prirae4.tfs 
primes. tfs 
primes. tfs 



Gr\NtTF}i:ES\PEPPER\PROGRAHWrFS 

PASS.TFS Dec 20. 1989 12:13pni 2341 bytes 



The Restore dialog box works just like the profiler's other file- 
loading dialog boxes. You can 

■ enter a file name or a specification (with DOS wildcards) in the 
File Name input box 

■ choose a different disk drive or directory from the directory tree 

■ choose a file name from the Files Hst box 

■ choose OK to complete the transaction (or choose Cancel to 
leave the dialog box without loading a file) 

■ choose Help to open a window of information about how to use 
the dialog box 

After you type in or choose a .TFS file name and load that file. 
Turbo Profiler restores all the saved options, settings, and 
resulting statistical information to the environment screen. 
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Print menu 



statistics 
Module... 



Options. 



Statistics 



The Pick a Module dialog 
box 



Turbo Profiler's Print menu enables you to print the contents of 
any open profiler window to a new or existing disk file, or 
directly to the printer. 

The Print I Statistics command prints the contents of all open 
profiler windows (except the Module window) to the printer, or to 
the destination file named in the Printing Options dialog box. 

Before you choose Print I Statistics, open the Printing Options 
dialog box (choose Print I Options) and verify that the current 
printing options (dimensions, output location, character set used, 
and — ^if you're printing to a file — destination file name) are what 
you want. 

If you choose to print statistics to an existing disk file, a menu 
pops up so you can choose whether to append the existing file, 
overwrite it, or cancel the printing operation. 

From the Pick a Module dialog box accessed by choosing Print I 
Module, you specify which of your program's modules you want 
printed to the printer or to the disk file named in the Printing 
Options dialog box. 

When you choose Module, this Pick a Module dialog box comes 
up: 

Figure 4.34 ir=["]=Pick a niodule= 



Append 

Overwrite 

Cancel 



IVioduIe 



Muie 



nndules 
PRIHEO 



ivm^Msss^jpitmr:^ 



You can choose a specific module by name, or choose All Modules 
to print all your program's available source code. When the 
profiler prints a module, it produces an annotated source listing — 
which lists execution time and counts data next to each source 
line or routine you've marked as an area, as shown in the 
following figure. 
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Figure 4.35 

Annotated source listing for 

PRiiVlEl 



Program: C:\TPR0FILE\PRIHE1.EXE File PRIHEl.C 


Time Counts 


Unclude <stdio.h> 


0.0090 999 


pr1nie(1nt n) 




{ 


int i; 


0.0117 999 
1.1456 78022 
0.0080 831 
0.0017 168 
0.0101 999 


} 


for (1-2! 1<n; i-H-) 

if (n % i -- 0} 
return 0; 
return 1; 


0.0000 1 


malnO 


Int 1. n: 


0.0000 1 
0.0000 1 
0.0255 999 
4.1670 168 
0.0000 1 


} 


n - 1000: 

for (1-2: K-n: i++) 

if (prinie(i)) , 

printfC*d\n", i): 



Options When you choose Options from the Print menu, this Printing 
Options dialog box comes up: 



Figure 4,36 

The Printing Options dialog 

box 



irW- 



=Printing options^ 




■ Width is the number of characters printed per line (default = 
80). 

■ Height is the total number of Hnes per page (default = 66). 

■ The Printer/File radio buttons let you choose between sending 
the printed statistics to the current printer or to a file. The 
default is Printer. 

■ The Graphics/ ASCII radio buttons let you toggle between 
printing characters from the IBM extended character set 
(including semigraphic characters) and printing only ASCII 
characters. The default is ASCII. 

■ Destination File is the disk drive (optional), path name 
(optional), and file name (required) of the printed disk file. 
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Options menu 



Macros ► 
Display options... 
Path for source... 
Save options... 
Restore options... 



With the Options menu, you can 

B record a menu-command macro 

D remove one or all menu-command macros 

El set display options that control Turbo Profiler's overall 
appearance and operation 

B specify directories (other than the current one) where Turbo 
Profiler will search for source code 

□ save your window layout, macros, options set in other menus, 
and some other miscellaneous options to a configuration file 

Q restore the settings and options previously saved in a 
configuration file 



Macros 



Create... 


Alt - 


Stop recording 


Alt - 


Remove 




Delete all 





The Options I Macro command leads to another menu, shown 
here. 

With the commands on this Macro menu, you can define new 
macros or delete ones you've already assigned to a key. Mouse 
actions are not included in a macro. 

To begin a macro recording session, 

1. Choose Options I Macro I Create. 

A prompt asks for which key to assign the macro to. T5^e in a 
keystroke or combination of keys (for example, Alt-M). The 
message recording appears in the upper right comer of the 
screen while you record the macro. 

2. Type the keystrokes you want to record. The profiler responds 
normally to these keystrokes and mouse actions, as if you 
weren't recording a macro. 

When you finish recording keystrokes, choose Options I 
Macros I Stop Recording (or press the key you assigned the 
macro to — Alt-M in this example) to stop the recording session. 

How macro recording and playback works 

With the profiler's macro recording facihty, you can record your 
frequently used keystroke sequences. During profiling, for 
example, you often repeat the same sequence of commands to get 
to a certain place in your program. This can be very tedious. 
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But, with Options I Macro, you can define a macro that records all 
the keys you press from the moment you first start the profiler 
imtil you have your program in the desired state. At that point, 
you can stop recording. If you must get back to the same place in 
your program, simply replay the macro. 

You can't use Options I Macro to record keystrokes that must be 
typed as input to your program. You can only record Turbo 
Profiler commands. 

To record your entire profiling session, 

1. Start Turbo Profiler from DOS. 

2. Choose Options I Macros I Create (or press Alt=) to define the 
macro. A prompt appears, asking which key you want the 
macro assigned to. 

3. Choose a key that hasn't been assigned to a routine yet, such 
as Shift and a routine key {Shift-F10, for example). 

4. Load your program. Turbo Profiler will automatically restore 
area settings from your program's .TFA file. 

5. If you want to use a configuration different from the default, 
load the appropriate config file (choose Options I Restore). 

6. Run your program: Stop execution if necessary. 

7. Stop recording the macro: Choose Options I Macros I Stop 
Recording (or press Alt-). 

8. Save the macro to a configuration file: Choose Options I Save 
Options, choose Macros in the Save Configuration dialog box, 
type the name of the corresponding configuration file (if you 
don't want to use the one listed in the dialog box), then choose 
OK or press Enter. 

9. Continue running your program. 

If your program requires you to type things to get to the next part 
of the recorded command sequence, you still must enter those 
keystrokes manually (you can do this while the macro is running). 
For programs that don't require any input, this command- 
recording mechanism can completely automate the restart 
procedure, saving many keystrokes. 

When you save a macro to a configuration file, the profiler saves 
the total environment configuration, including opened and 
zoomed windows. So, if you record a macro that opens a window, 
and you don't close the window before saving the macro, the next 
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. time you restore that configuration file, the window opens 
automatically — even if you don't execute the macro. 

Create (Alt=) 

The Create command starts recording keystrokes that you want 
assigned to a macro key. Alt= is the hot key for Create. 

Stop Recording (Alt-) 

The Stop Recording command stops recording the keystrokes 
you're assigning to a macro key. Use this command after choosing 
Options I Macros I Create. Alt- is the hot key for Stop recording. 

Remove 

The Remove command removes a macro assigned to a single key. 
A prompt asks you to press the key of the macro you want 
removed. 

Delete 

The Delete command removes all keystroke macro definitions and 
restores all keys to their original (default) meanings. 

Display Options The Options I Display Options command opens the Display 
Options dialog box, shown here. 

Figure 4.37 

The Display Options dialog 

box 




With the Display Options dialog box, you can do any of the 
following: 

■ specify whether Turbo Profiler will swap screens while your 
program runs 

■ set how many columns each tab stop occupies in the Module 
window 

■ set the Turbo Profiler screen to 25-line or 43/50-line mode 
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1 specify how wide your program's routine names display in the 
Execution Profile and Areas windows. 



Display Swapping 

The Display Swapping radio buttons provide two options for how 
Turbo Profiler swaps the User screen back and forth with the 
Turbo Profiler environment: None, and Always. 

u None means don't swap between the two screens. 

Use this option if you're profiling a program that does not send 
any output to the User Screen. 

■ Always means swap to the User Screen every time your pro- 
gram runs. 

Use this option if your program does writing to the screen. 

Screen Lines 

You use Screen Lines to specify whether Turbo Profiler's screen 
uses the normal 25-line display or the 43- or 50-line display 
available on EGA and VGA display adapters. 

One or both of these buttons will be available, depending on the 
type of video adapter in your PC. The 25-Hne mode is the only 
screen size available to systems with a monochrome display or 
Color Graphics Adapter (CGA). 

Tab Size 

With the Tab Size input box, you set how many columns each tab 
stop occupies, from 1 to 32 columns. You can reduce the tab 
column width to see more text in source files with a lot of tab- 
indented code. 



Width of Names 

The Width of Names input box is where you specify how wide 
routine names display in the Execution Profile, Callers, and Areas 
windows. 
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Path for Source By default. Turbo Profiler looks for your program's source code in 
these places, in this order: 

1. In the directory where the original compiler found the source 
files 

2. In the current directory 

3. In the directory that contains the program you're profiling 

With the Options I Path for Source command, you can add a list of 
directories that Turbo Profiler searches before it searches in the 
current directory. 

Enter the new to-be-searched directories in this format: 

Directory; Directory; Directory 

For example, 

C:\Borland\TC; C:\Borland\TASM 



Save Options 



Figure 4.38 

The Save Configuration 

dialog box 



With Options I Save Options, you can save all your current 
profiler options to a configuration file on disk. Then, whenever 
you want to reset the profiler options to those saved settings, you 
can load that configuration file with Options I Restore Options. 

When you choose Options I Save Options, the following Save 
Configuration dialog box comes up: 

ii=[«]=Save Conf1guration= 



r 


^ Tiptlons ■ Ok J 
. J Uyout ni"""'""'T| 
' ] Macros Uncancel ■■ 


■■'■gave To" ' .;"■:•■■■-"'"■■"■/ 


^^KmitnKmimm Binnr 





With this dialog box, you can save your current profiler setup's 
options, layout, and macros. Options, Layout, and Macros are 
check boxes; you can save one, two, or aU three types of 
information to a configuration file. 

B Options are menu options not saved in a .TFA or .TFS file (such 
as Options I Path for Source, command-line options, and 
settings in the Display Options dialog box). 

o Layout includes which windows are currently open, plus their 
order, position, and size. 
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Restore 



Figure 4,39 
The Restore dialog box 



■ Macros are all keystroke macros currently defined. 

■ Save To lists the default configuration file, TFCONFIG.TF. To 
save your options there, choose OK (or press Entef). 

To save them to a different file, type in the different file's name 
(including disk drive and path, if you want), then choose OK 
(or press Enter). 

Once you've saved options to a configuration file, you can recover 
them at any time with Options I Restore. 

Options I Restore restores your profiling options from a disk file. 
You can have multiple configuration files, containing different 
macros, window layouts, and so on. 

When you choose Options I Restore, this dialog box comes up: 

=Enter name of configuration fne= 




GT\NE1 H LES\PEPPER\;PR0GRAHX*7TF- 



The Restore dialog box works just like the profiler's other file- 
loading dialog boxes. You can 

■ enter a file name or a specification (with DOS wildcards) in the 
File name input box 

■ choose a different disk drive or directory from the directory tree 

■ choose a file name from the Files list box 

■ choose OK to complete the transaction (or choose Cancel to 
leave the dialog box without loading a file) 

■ choose Help to open a window of information about how to use 
the dialog box 

After you type in or choose a configuration file name and load 
that file. Turbo Profiler restores aU the saved options, settings, 
layout, and macros to the current Turbo Profiler environment. 
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(You can only restore a configuration file that was created by the 
Options I Save Options command.) 



Window menu 



Zoom 


F5 


Next 


F6 


Next pane 


Tab 


Size/move 


Ctrl-F5 


Iconize/restore 




Close 


AU-F3 


Undo close 


Alt-F6 


User screen 


Alt-F5 


1 Module 




2 Profile 





The Window menu contains commands to 

a manipulate Turbo Profiler's windows 

B navigate within and through the windows 

m toggle windows to icons, and vice versa 

B close and reopen windows 

B go to your program's output screen 

B make an open window active 

The commands in the top portion of the Window menu are for 
moving about within the profiler's windowed environment and 
for rearranging the windows to your satisfaction. Most Tiu-bo 
Profiler windows have aU the standard window elements (scroU 
bars, a close box, zoom icons, and so on). Refer to page 65 for 
information on these elements and how to use them. 



Zoom The Zoom command zooms the active window (the one with a 
double-line border) to full-screen. 

Next The Next command activates the window whose number succeeds 
the number of the current window. 

Ne>d" Pane In windows with multiple panes,the Next Pane command moves 
the cursor to the next pane. 

Size/Move The Size/Move command activates Turbo Profiler's window- 
arranging mode. You move the current window with <— , ->, T and 
i arrow keys. Shifted arrow keys expand or contract the window. 
The legend in the status line explains which key combinations do 
which action. The hot key for this command is Ctrl-F5. 



Iconize/Restore 



The Iconize/Restore command shrinks the active window to an 
icon or restores the active icon to a window. Figure 4.40 shows 
windows and icons on the Turbo Profiler screen. 

Turbo Profiler's iconize feature is a handy tool for keeping several 
windows open without cluttering up the screen. A window icon is 
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Figure 4.40 
Windows and window icons 



a small representation of an open window, as shown in the 
following figure. 



'Ftir»vigr!Mi 

-fioduTe: PRII 



un statistics Li"! ft iptions ;indow lelp 



PRIHEO File: prlmeO.c (modified) 7- 



/* Copyright (c) 1990, Borland International */ 

/* Program for generating prime numbers using Euclid's method •/ 

int primes [1000]; 
Idefine HAXPRIKES 1000 

•► mainO 

Int j: 

Int lastprime, curpriroe; 



=========== [pW=5=[t]=ii= 

=========== Disassembly ♦— — Acti ve======== 



:icon=: 



Icons 



SBESSBf 
iSSShiiSS 



■■■■■fc========================iMM 



Alt: FiBraaianiF2B™«ma«a:iragaiBaiFsHTmaF6mnCTFi(gwCT»mtM^ 



To make a window into its icon, choose Iconize/Restore from the 
Window menu, or click the iconize box in the window's top frame. 
To restore an icon to its previous size, choose Iconize/Restore 
again, or click in the icon's zoom box. 

Close The Close command temporarily removes the current window 

from the Turbo Profiler screen. To redisplay the window just as it 
was, choose Undo Close. 

Undo Close The Undo Close command reopens the most recently closed 
window and makes it the active window. 

To go to one of the open windows listed in the bottom portion of 
the Window menu, choose the window from the list (click it or 
press the listed ntmiber). For a full explanation of how to manage 
windows, see page 67. 



User Screen Choose Window I User Screen (or press M-F5) to view your 
program's full-screen output. 

Press any key to return to the windowed environment. 



Alt F5 
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The open window list 



At the bottom of the Window menu is a numbered list of open 
windows. Press the number corresponding to one of these 
windows to make it the active window. 



Help menu 



Index Shift-Fl 

Previous topic Alt-Fl 
Help on help 



nn 



index 



Previous Topic 



The Help menu gives you access to online help in a special 
window. There is help information on virtually all aspects of the 
environment and Turbo Profiler. (Also, one-line menu and dialog 
hints appear on the status line whenever you select a command.) 

To open the Help window, do one of these actions: 

a Press F1 or Alt-F1 at any time (including from any dialog box or 
when any menu command is selected). 

D Click Help whenever it appears on the status line or in a dialog 
box. 

To close the Help window, press Esc, cUck the close box, or choose 
Window I Close. 

Help screens often contain keywords (highhghted text) that you 
can choose to get more information. Press the arrow keys to move 
to any keyword; then press Enter to get more detailed help on the 
chosen keyword. (As an alternative, use the arrow keys to move 
to any keyword, then press Enter to choose it). You can press Home 
and End to go to the first and last keywords on the screen, 
respectively. With a mouse, you can click any keyword to open 
the help text for it. 

The Help I Index command opens a dialog box displaying a full list 
of help keywords (the special highghted text in help screens that 
let you quickly move to a related screen). 

You can page down through the list. When you find a keyword 
that interests you, choose it by using the arrow keys to move to it 
and press Enter. (You can also double-click it.) 

The hot key for Help I Index is Shift-F1. 

The Help I Previous Topic command opens the Help window and 
redisplays the text you last viewed. 

Turbo Profiler lets you back up through 20 previous help screens. 
You can also click the PgUp command in the status line to view the 
last help screen displayed. 
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Help on Help The Help I Help on Help command opens up a text screen that 
explains how to use the Turbo Profiler help system. 
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Turbo Profiler's command-line options 



This is the generic command-line fonnat for running Turbo 
Profiler: 

TPROF [tprof_options] [progname [program_args]] 

where tprofjjptions is a list of one or more command-line options 
for the profiler (see Table A.l). progname is the name of the 
program you want to profile. program_args is a list of one or more 
command-line arguments for the profiled program. 

You can type tprof without a program name or any arguments; if 
you do, you must then load the program you want to profile with 
Turbo Profiler's environment. 

Here are some example Turbo Profiler command lines: 

tprof -sc progl a b Starts the profiler with the -sc option and 
loads program PROGl with two command- 
line arguments, a and b. 

tprof prog2 -x Starts the profiler with default options and 

loads program PROG2 with one argument. 
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The connnnand-line options 



Table A.l 

Turbo Profiler command-line 

options 



All of Turbo Profiler's command-line options start with a h5^hen 
(-). At least one space or tab separates each option from the 
TPROF command and any other command-line components. 

To turn an option off at the command line, type a hyphen after the 
option. For example, -vg- explicitly turns the graphics save option 
off. Normally you'U only turn an option off if it's permanentiy 
enabled in the profiler's configuration file, TFCONFIG.TF. (You 
can modify the configuration file with the TFINST installation 
program described in the Introduction to this manual.) 

Table A.l summarizes Turbo Profiler's command-line options; we 
cover these options in greater detail in the following pages. 

Option What it does 

-cfile Reads in configuration file /ik. 

-do Runs the profiler on a secondary display. 

-dp Shows the profiler on one display page, the output of the 
profiled program on another. 

-ds Maintains separate screen images for the profiler and the 
program being profiled. 

-h Displays a help screen. 

-? Also displays a help screen. 

-i Enables process ID switching. 

-mW Sets the working heap size to N kilobytes. 

-p Enables mouse support. 

-r Enables profiling on a remote system over a serial link. 

-rpW Sets the remote link port to port N. 

-rsW Sets the remote link speed. 

-sc Ignores case when you enter symbol names. 

-sd Sets one or more source directories to scan for source files. 

-vg Saves complete graphics image on program screen. 

-vn Disables 43/50 line display. 

-vp Enables EGA palette save for program output screen. 

-y/V Sets overlay area size to N kilobytes. 

-yeW Sets EMS overlay area size to N 16K pages. 
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Configuration file 

(-C) This option tells Turbo Profiler to use the indicated configuration 
file. The default is TFCONVIG.TF; if you want to load a different 
one, you must use -c, followed immediately (no space) by the 
name of the configuration file you want to use. 

Display update 

(-d) All -d options affect the way Turbo Profiler updates the display. 

-do Runs the profiler on a secondary display. You can view 
the program's screen on the primary display while 
Turbo Profiler runs on the secondary display. 

-dp This is the default option for color displays. Shows the 
profiler on one display page, and the ou^ut of the 
program being profiled on another. 

Using two display pages minimizes the time it takes to 
swap between two screens. You can only use this 
option on a color display, because only color displays 
have multiple display pages. You can't use this option 
if the profiled program uses multiple display pages. 

-ds This is the default option for monochrome displays. 
Maintains separate screen images for the profiler and 
the program being profiled. 

Each time you run the program or reenter the profiler. 
Turbo Profiler loads an entire screen from memory. 
This is the most time-consuming method of displaying 
the two screen images, but it works on any display and 
with programs that do unusual things to the display. 



Help (-h and -?) 



Both of these options display Turbo Profiler's command-line 
syntax and options. 
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Figure A.l 
Turbo Profiler DOS-level help 



Syntax: TA [options] [program [arguments]] -x- - turn option x off 


-c<file> 


Use configuration file <file> 


-do.-dp.-ds 


Screen updating: do-Other display. dp-Page flip. ds-Screen swap 


-h,-7 


Display this help screen 


-i 


AlloN process id switching 


-ra<#> 


Set heap size to # kbytes 


-P 


Use mouse 


-r 


Use remote analysis 


-rp<#> 


Set COM # port for remote link 

Remote link speed: l-s1ow. Z-roediuro. 3-fast 


-rs<#> 


-sc 


No case checking on symbols 


-sd<dir> 


Source file directory <dir> 


-vg 


Complete graphics screen save 


-vn 


43/50 line display not allowed 


-vp 


Enable EGA/VGA palette save 


-y<#> 


Set overlay area size in Kb 


-ye<#> 


Set EHS overlay area size to # 16Kb pages 



Process ID 
switching (-1) 

IVIodIfy heap size 
(-m) 



Use this option to enable process ID switching. 



This option sets the working heap to N Kbytes; the syntax is 

-mN 

The default working heap size is 40K; the high boundary is 64K. If 
your program needs memory, use -m to reduce the amount of 
heap Turbo Profiler uses. You can also use -m to increase the 
amount of heap when profiling smaU programs. This option lets 
Turbo Profiler store transient information, such as command 
history lists, in the high end of the heap. 

If TPROF runs out of memory, you get an error message 
whenever you try to open windows or perform other memory- 
consuming tasks. Statistics such as Callers may also be truncated. 



Mouse support 
(-P) 



This option enables mouse support. 



Remote profiiing 
(-0 



All -r options affect Turbo Profiler's remote profiling link. 

-r Enables profiling on a remote system over a serial link. 

Uses the default serial port (COMl) and speed (115 
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Kbaud), unless these have been changed using 
TFINST. 

-rpN Sets the remote link port to port N. Set N = 1 for 
COMl;N = 2forCOM2. 

-rsN Sets the remote link speed to the value associated with 
N, as shown here: 



N Speed 



1 9600 baud 

2 40 Kbaud 

3 115 Kbaud 



Source code and 

symbols (-S) A11 -s options affect the way Turbo Profiler handles source code 
and program S3nTibols. 

-sc Ignores case when you enter symbol names, even if 
your program has been Hnked with case-sensitivity 
enabled. 

Without the -sc option. Turbo Profiler ignores case 
only if you've linked your program with the "case 
ignore" option enabled. 

Note: The -sc option has no effect if you're profiling a 
Turbo Pascal program. Turbo Pascal is not case- 
sensitive. 

-sd Sets one or more source directories to scan for source 
files; the S)nitax is 
Like this, with no space 
beiween -sd and the "sddi rname 

irec ory name. dirname can be a relative or absolute path and can 

include a disk letter. To set multiple directories, use the 
-sd option for each one. (You can only specify one 
directory name with each -sd option.) Turbo Profiler 
searches directories in the order specified. 

If the configuration file specifies a directory list, the 
profiler appends the ones specified by the -sd option 
to that list. 
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Video hardware 
(-V) 



All -V options affect how Turbo Profiler handles the video 
hardware. 

-vg Saves the program screen's complete graphics image. 
Requires an extra 8K of memory, but allows you to 
profile programs that use special graphics display 
modes. Try this option if your program's graphics 
screen becomes corrupted when running under Tiirbo 
Profiler. 

-vn Disables the 43/50 Hne display mode. Specify this 
option to save some memory. Use -vn if you're 
running on an EGA or VGA and know you won't 
switch into 43- or 50-line mode once Turbo Profiler is 
running. 

-vp Enables you to save the EGA/VGA palette for the 

program output screen. Use this option for programs 
that output to special EGA/VGA graphics modes. 



Overlay area size 
(-y) 



The -y options are used to set the size of the overlay area size, 
either in main memory or in EMS memory. 

-yN This option sets the overlay area size in main memory. 

The syntax is as foUows, where N is the number of 
kilobytes you want to reserve: 

-yW 

Normally, Turbo Profiler uses a 80K code area size. The 
smallest area size that you can set is 20K. The largest is 
250K. 

Use this option if you do not have enough memory to 
load your program under Turbo Profiler, or if you are 
debugging small programs and want to improve Turbo 
Profiler's performance. The smaller the code area size, 
the more often Turbo Profiler loads program overlays 
from disk, and the slower it responds. With a larger 
code area, there is less memory available for the 
program you are profiling, but Turbo Profiler runs 
faster. 
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-yeN This option sets the overlay area size in EMS memory. 
Use this option if you need to free up some EMS 
memory for the program you are profiling. The syntax 
is as follows, where N is the number of 16K EMS pages 
you want to reserve: 

-yW 

For example, -ye4 sets the overlay area to four pages. 
The default is twelve 16K EMS pages. 
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B 



Customizing Turbo Profiler 



Turbo Profiler is ready to run as soon as you make working 
copies of the files on the distribution disk. However, you can 
change many of the default settings by running the customization 
program called TFINST. You also can change some of the options 
using command-line options when you start Turbo Profiler from 
DOS. If you find yourself frequently specifying the same com- 
mand-line options over and over, you can make those options 
permanent by running the customization program. 

The customization program lets you set the following items: 

■ Window and screen colors and patterns 

■ Display parameters: screen swapping mode, integer display 
format, beginning display (source or assembler code), screen 
lines, tab column width, maximum tiled Watches size, fast 
screen update, 43-/50-line mode, full graphics saving. User 
screen updating, and log list length 

■ Your editor startup command and directories to search for 
source files and the Turbo Profiler help and configuration files 

■ User input and prompting parameters: history list length, beep 
on error, mouse, keystroke recording, and control-key shortcuts 

■ Source profiling: language options and case sensitivity 

■ NMI intercept, DOS process ID switching, expanded memory 
specification (EMS) for symbol table, and remote profiling 

■ Display mode 
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Running TFiNST 



To run the customization program, enter TFINST at the DOS 
prompt. As soon as TFINST comes up, it displays its main menu. 
You can either press the highlighted first letter of a menu option 
or use the T and i keys to move to the item you want and then 
press Enter. For instance, press D to change the display settings. 
Use this same technique for choosing from the other menus in the 
installation utility. To return to a previous menu, press Esc. You 
may have to press Esc several times to get back to the main menu. 

Getting out Choose File I Quit (Alt-X) at the menu bar to exit TFINST. 



Colors 




► 


Display... 






Options 




► 


Mode for dl 


splay 


► 


Save 




► 


Quit 







Setting the screen colors 



Choose Colors from the main menu to bring up the Colors menu. 
It offers you two choices: Customize and Default Color Set. 



Customizing 
screen colors 



If you choose Customize, a third menu appears, with options for 
customizing windows, dialog boxes, menus, and screens. 



Windows To customize windows, choose the Windows command. This 
opens a fourth menu, from which you can choose the kind of 
window you want to customize: Text, Statistics, and Disassembly 
(the CPU window). Choosing one of these options brings up yet 
another menu listing the window elements, together with a pair 
of sample windows (one active, one inactive) in which you can 
test various color combinations. The screen looks like this: 
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Figure B.l 

Customizing coiors for 

windows 



Turbo 'Prof ileranstaVlationf5Vl-iOgi56i!i(C)!!5l989'(BonUnd!|lnternatm 




gB^^SSSHiS 



SSiiBSl 
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When you select an item you want to change, a palette box pops 
up over the menu. Use the arrow keys to move around in the 
palette box. As you move the selection box through the various 
color choices, the window element whose color you are changing 
is updated to show the current selection. When you find the color 
you like, press Enter to accept it. 

c:J)> Turbo Profiler maintains three color tables: one for color, one for 
black and white, and one for monochrome. You can only change 
one set of colors at a time, based on your current video mode and 
display hardware. So, if you are running on a color display and 
want to adjust the black-and-white table, first set your video 
mode to black and white by typing mode bw80 at the DOS prompt, 
and then run TFINST. 

Dialog boxes and If you choose Dialogs or Menus from the Customize menu, a 

menus screen appears with a menu listing dialog box or menu elements, 
and a sample dialog box or menu for you to experiment with. 

As with the Windows menu, choosing an item from the current 
menu opens a palette from which you can choose the color for 
that item. 
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Screen 



Pattern for background ► 



Pattern background 
Pattern foreground 
Ulndow move background 



Window move foreground 



The default colors 



Choosing Screen from the Customize menu opens a menu from 
which you can access another menu with screen patterns and 
palettes for screen elements, as well as a sample screen back- 
ground on which to test them. 



If you choose Default Color Set from the Colors menu, facsimiles 
of an active text window and an inactive window appear 
onscreen, which show you the default colors for their elements. A 
dialog box lets you select text, statistics, or low-level windows to 
view. 



Setting Turbo Profiler display parameters 



Figure B.2 

The Display Options dialog 

box 



o 



Display Swapping 



Choose Display from the main menu to bring up the Display 
Options dialog box. 

ip[«3^= =Ci splay options=== 



Display swapping 



f ; ft I ways 



Screen lines 



User screen updating 




These display options include some you can set from the DOS 
command line when you start up Turbo Profiler, as weU as some 
you can set only with TFINST. See page 148 for a table of Turbo 
Profiler command-line options and corresponding TFINST 
settings. 



You use the Display Swapping radio buttons to control how 
Turbo Profiler switches between its own display and the output of 
the program you're profiling. You can toggle between the 
following settings: 
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Screen Lines 



None Don't swap between the two screens. Use this option if 
you're profiling a program that does not output to the 
User screen. 

Always Swap to the User screen every time the user program 
runs. Use this option if your program writes to the 
User screen. 

This is the default option. 



Use these radio buttons to toggle whether Turbo Profiler should 
start up with a display screen of 25 lines or a display screen of 43 
or 50 lines. 



dD> Only the EGA and VGA can display more than 25 lines. 



Fast Screen 
Update 



The Fast Screen Update check box lets you toggle whether your 
displays will be updated quickly. Toggle this option off if you get 
"snow" on your display with fast updating enabled. You need to 
disable this option only if the "snow" annoys you. (Some people 
prefer the snowy screen because it gets updated more quickly.) 



Permit 43/50 Lines 



Full Graphics 



Turning this check box on allows big (43-/50-ltne) display modes. 
If you turn it off, you save approximately 8K, since the large 
screen modes need more window buffer space in Turbo Profiler. 
This may be helpful if you are profiling a very large program that 
needs as much memory as possible to execute in. When the option 
is disabled, you will not be able to switch the display into 43-/50- 
line mode even if your system is capable of handling it. 



Saving Turning this check box on causes the entire graphics display 

buffer to be saved whenever there is a switch between the Turbo 
Profiler screen and the User screen. If you turn it off, you can save 
approximately 12K of memory. This is helpful if you are profiling 
a very large program that needs as much memory as possible to 
execute. Generally the only drawback to disabling this option is a 
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small number of corrupted locations on the User screen that don't 
usually interfere with profiling. 

Tab Size 

In this input box, you can set the number of columns between tab 
stops in a text or source file display. You are prompted for the 
number of columns (a number from 1 to 32); the default is 8. 

User Screen 

U pdoting The user Screen Updating radio buttons set how the User screen 
is updated when Turbo Profiler switches between its screen and 
your program's User screen. There are three settings: 

Other Display Runs Turbo Profiler on the other display in 
your system. If you have both a color and 
monochrome display adapter, this option lets 
you view your program's screen on one 
display and Turbo Profiler's on the othen 

Flip Pages Puts Turbo Profiler's screen on a separate 

display page. This option works only if your 
display adapter has multiple display pages, 
like a CGA, EGA, or VGA. You can't use this 
option on a monochrome display. This option 
works for the majority of profiling situations; it 
is fast and disturbs only the operation of pro- 
grams that use multiple display pages — which 
are few and far between. 

Swap Uses a single display adapter and display 

page, and swaps the contents of the User and 
Turbo Profiler screens in software. This is the 
slowest method of display swapping, but it is 
the most protective and least disruptive. If you 
are profiling a program that uses multiple 
display pages, use this option. Also use the 
Swap option if you shell to DOS and run other 
utilities or if you are using a TSR (such as 
SideKick Plus) and want to keep the current 
Turbo Profiler screen as well. 
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Turbo Profiler options 



Directories... 
Input & prompting... 
Miscellaneous... 



The Options command in the main menu opens a menu of 
options, which in turn open dialog boxes for you. 



The Directories 

diolog box This dialog box contains input boxes in which you can enter: 



Editor program name 



Source directories 



Turbo directory 



Specifies the DOS command that starts 
your editor. This lets Turbo Profiler start 
up your favorite editor when you are 
profiling and want to change something 
in a file. Turbo Profiler adds to the end of 
this command the name of the file that it 
wants to edit, separated by a space. 

Sets the list of directories Turbo Profiler 
searches for source files. 

Sets the directory that Turbo Profiler 
searches for its help and configuration 
files. 



The User input 

and Prompting 

dioiog box 

Figure B.3 

The User Input and Prompting 

dialog box 



This dialog box lets you set options that control how you input 
information to Turbo Profiler, and how Turbo Profiler prompts 
you for information: 
=[■]=== 




History List Length 



This input box lets you specify how many earlier entries are to be 
saved in the history list of an input box. 



Beep on Error By default. Turbo Profiler gives a warning beep when you press 
an invalid key or do something that generates an error message. 
The Beep on Error check box lets you change this default. 



Appendix B. Customizing Turbo Profiler 



145 



Mouse Enabled 



This check box controls whether Turbo Profiler defaults to mouse 
support. 



Control Key Shortcuts 



This check box enables or disables the control-key shortcuts. 
When control-key shortcuts are enabled, you can invoke any local 
menu command directly by pressing the Ctrl key in combination 
with the first letter of the menu item. However, in that case, you 
can't use those control keys as WordStar-style cursor-movement 
commands. 



The Miscellaneous 

Options dialog 

box 



Figure B.4 

The Miscellaneous Options 

dialog box 



The Miscellaneous Options dialog box contains options control- 
ling interrupts, EMS memory, DOS shell swapping, and remote 
profiling. 



lr=W= 



=H1scel1aneous options^ 



Printer output 

■Qi iiiwi»MazniiEgi DaKszE^EEiUTiinia 



Use expanded mennry 

NHI Intercept 

lonore case of svrnbol s 



OS shell swap size (Kb) 



Remote link port 



Link speed 



i£!mr 



Printer Output This option lets you toggle whether to print both high and 

standard ASCII characters, or just the straight standard ASCII 
character set. 



Use Expanded Memory 



Use this check box to toggle whether Turbo Profiler uses EMS 
memory for symbol tables. You can enable this option even if 
your program uses EMS as well. 



NMI Intercept If your computer is a Tandy lOOOA, IBM PC Convertible, or NEC 
MultiSpeed, or if Turbo Profiler hangs loading your system, run 
THNST and turn off the NMI Intercept check box. Some 
computers use the NMI (nonmaskable interrupt) in ways that 
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conflict with Turbo Profiler, so you must disable Turbo ProfQer's 
use of this interrupt in order to run the program. 

Ignore Case of Symbol If this check box is turned on. Turbo Profiler defaults to treating 

uppercase and lowercase the same. If it is off, case sensitivity is in 
effect. 

DOS Shell Swap Size In this input box you can set the number of kilobytes for to 

(Kb) increase the amount of memory set aside, so you can use the FUe I 
DOS Shell command even when a large program is loaded. 

Remote Analyzing This check box lets you toggle between enabling and disabling the 
remote link. 

Warning! Usually you won't want to turn this check box on, since that will 
mean that Turbo Profiler wiU start up every time using the remote 
Unk. 

Remote Link Port The Remote Link Port radio buttons let you choose between using 
the COMl or COM2 serial port for the remote Link. 

Link Speed The Link Speed radio buttons let you choose one of the three 
speeds that are available for the remote link: 9600 baud, 40,000 
baud, or 115,000 baud. 



Setting the mode for display 



Default 

Color 

Black and white 

Monochrome 

LCP 



Choosing Mode for Display from the main menu opens a menu 
from which you can select the display mode for your system. 



Default 

Turbo Profiler detects the kind of graphics adapter on your 
system and selects the display mode appropriate for it. 

Color 

If you have an EGA, VGA, CGA, MCGA, or 8514 graphics adapter 
and choose this as your default, the display will be in color. 
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Black and White 

If you have an EGA, VGA, CGA, MCGA, or 8514 graphics adapter 
and choose this as your default, the display will be in black and 
white. 



Monochrome 

Choose this if you are using a color monitor with a Hercules or 
monochrome text-only adapter. 



LCD 

Choosing this instead of Black and White if you have an LCD 
monitor makes your display much easier to read. 



Command-line options and TFINST equivalents 



Table B.l 

Command-line options and 

TFINST equivalents 



Some of the options described in the previous section can be over- 
ridden when you start Turbo Profiler from DOS. The following 
table shows the correspondence between Turbo Profiler com- 
mand-line options and the TFINST program conm\and that 
permanently sets that option. 



Option 



-do 
-dp 
-ds 



-P 
-P- 

-r 
-r- 

-rpl 
-rp2 

-rsl 
-rs2 



TFINST menu path and dialog box 



Display I Display Options 

(•) Other Display 
(•) Flip Pages 
(•) Swap 

Options I Input and Prompting I User Input and 
Prompting 

[X] Mouse Enabled 
[ ] Mouse Enabled 

Options 1 Miscellaneous I Miscellaneous Options 

[X] Remote Profiling 
[ ] Remote Profiling 

Options I Miscellaneous I Miscellaneous Options 

(•) COMl 
(•) COM2 

Options I Miscellaneous I Miscellaneous Options 

(•) 9600 Baud 
(•) 40 KBaud 
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Table B.l : Command-line options and TFINST equivalents (continued) 



O 



-rsS 



-sc 
-sc- 

-sd 



-vn 
-vn- 



(•) 115 KBaud 

Options i Miscellaneous I Miscellaneous Options 

[X] Ignore Case of Symbol 
[ ] Ignore Case of Symbol 

Options I Directories I Directories 

Source Directories 

Display I Display Options 

[ ] Permit 43/50 Lines 
[X] Permit 43/50 Lines 



For a list of all the command-line options available for 
TFINST.EXE, enter the program name followed by -h: 



When you're through... 



Saving changes 



Save configuration file... 
Modify TPROF.EXE 



When you have all your Turbo ProfQer options set the way you 
want, choose Save from the main menu to determine how you 
want them saved. 



Save Configuration File 



If you choose Save Configuration File, a dialog box opens, initial- 
ized to the default configuration fUe TFCONFIG.TF. You can 
accept this name by pressing Enter, or you can type a new 
configuration file name. If you specify a different file name, you 
can load that configuration by using the -c command-line option 
when you start Turbo Profiler. For example, 

tprof -cmycfg myprog 

You can also use the Turbo Profiler Options I Restore Configu- 
ration command to load a configuration once you have started 
Turbo Profiler. 



IVlodlfy TPROF.EXE 



O 



If you choose Modify TPROF.EXE, any changes that you have 
made to the configuration are saved directly into the Turbo 
Profiler executable program file TPROF.EXE. The next time you 
enter Turbo Profiler, those settings will be your defaults. 

If at any time, you want to return to the default configuration that 
Turbo Profiler is shipped with, copy TPROF.EXE from your 
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master disk onto your working system disk, overwriting the 
TPROF.EXE file that you modified. 

Exiting TFINST 

To get out of TFDSJST at any time, choose Quit from the main 
menu. 
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A 



N 



D 



X 



c 



Remote profiling 



Before resorting to remote 

profiling, you mighit see if 

Turbo Profiler is talcing 

advantage of any EMS 

memory installed on your 

system. 



If your program requires a lot of memory, you may not be able to 
run both Turbo Profiler and your program on the same computer. 
Turbo Profiler's TFREMOTE utility solves this problem by letting 
you run Turbo Profiler on one system and the prog;ram you're 
profiling on another system. 

Here are some examples of when you'd use remote profiling: 

n When you attempt to load your program. Turbo Profiler gives 
one of these error messages: 

o "Not enough memory to load symbol table" 
o "Not enough memory" 

Q Your program loads properly under Turbo Profiler, but there's 
not enough memory left for it to operate properly. 

In this appendix, you'll see how to profile very large programs by 
using a second PC connected to your main PC. 



Remote hardware requirements 



To use remote profiling, you need the following equipment: 

□ a development system with a serial port (this is the local system, 
where you'll run Turbo Profiler) 
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■ another PC with a serial port and enough memory and disk 
space to hold the program you want to profile (this is your 
remote system) 

u a null modem or serial printer cable to connect the two systems 

Make sure that the cable connecting the two systems is set up 
properly: You can't use a straight-through extension-type cable. 
At the very least, the cable must swap the transmit and receive 
data lines (lines 2 and 3 on a 25-pin cable). 

Use the cable to connect the two serial ports. 

Installing TFREMOTE 

Copy TFREMOTE.EXE onto the remote system. Put any files 
required by the profiled program on the remote system. (This 
includes data-input files, configuration files, help files, and so on.) 

To put files on the remote system, you can use floppy disks or the 
TDRF Remote File Transfer Utility on the Turbo Debugger disks. 
(Ifs described in the MANUAL.DOC file for Turbo Debugger.) 

If you want, you can put a copy of the program you want to 
profile onto the remote system. This is not essential: Turbo 
Profiler sends it over the remote link if necessary. 

Once you start TFREMOTE and TPROF in remote mode, the 
Turbo Profiler commands work exactly the same as on a single 
system; there is nothing new to learn. 

Because the program you're profiling is actually running on the 
remote system, any screen output or keyboard input to that pro- 
gram happens on the remote system. The Window I User Screen 
command has no effect when you're running on the remote link. 

The remote system's CPU type appears as part of the CPU 
window title, with the word REMOTE before it. 

To send files over to the remote system while running Turbo 
Profiler, go to DOS (choose File I DOS Shell) and then use TDRF to 
perform file-maintenance activities on the remote system. 

To return to Turbo Profiler, type exit at the DOS prompt and 
continue profiling your program. 
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starting the 
remote link 



Before you start TFREMOTE on the remote system, set the current 
directory (the remote system's) where you want it. This is 
important because TFREMOTE puts the program to be profiled 
into the directory that is current when you start TFREMOTE. 

If the remote system's serial port is set up as COMl, type 

TFREMOTE -rpl -rs3 

to Start TFREMOTE. 

If the remote system's serial port is set up as COM2, type 

TFREMOTE -rp2 -rs3 

to Start TFREMOTE. 

Both of these commands start the link at its maximum speed (115 
Kbaud). This speed works with most PCs and cable setups. (See 
page 154 for how to start the link at a slower speed if you 
experience commimication difficulties.) Use the command-line 
option -rsl on a PS/2. 

TFREMOTE signs on with a copyright message, then indicates 
that it is waiting for you to start Turbo Profiler on the other end of 
the link. To stop and return to DOS, press Ctrl-Break. 



Starting Turbo 

Profiler on the 

remote link 



To start Turbo Profiler on the remote link, use one of the 
following DOS command lines: 

B serial port COMl: tprof -rpl -rs3 filename 
■ serial port COM2: tprof -rp2 -rs3 filename 

When the link starts successfully, the message "Waiting for 
handshake" appears on the remote system, and the activity 
indicator on the local system displays READY. Turbo Profiler's 
normal display then follows on tiie local system. Use the 
command-line option -rsl on a PS/2. 

TPROF and TFREMOTE use the same command-line options to 
set the speed and serial port: For them to work properly, you 
must set them both to the same speed (with the -rs option). 

Turbo Profiler also has the -r command-line option, which starts 
the remote link using the default speed and serial port. Unless 
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Loading the program 
to the remote system 



you've changed the defaults using TFINST, -r specifies COMl at 
115 Kbaud (the fastest baud speed.) 

Here's a tj^ical Turbo Profiler command line to start the remote 
link: 

tp -rs3 myprog 

This begins the link on the default serial port (usually COMl) at 
link speed 3 (115 Kbaud), and loads the program MYPROG into 
the remote system (if if s not already there). 

Turbo Profiler is smart about loading the to-be-profiled program 
onto the remote disk. It looks at the date and time of the copy of 
the program on the local system and the remote system. If the 
local copy is later (newer) than the remote copy, Turbo Profiler 
presumes you've recompiled or relinked the program and sends it 
over the link. At the highest link speed, this happens at a rate of 
about UK per second. A typical 60K program takes about six 
seconds to transfer, so don't be alarmed if there's a delay when 
you want to load a new program. 

To indicate that something's happening, the screen on the remote 
system adds up the bytes of the file as Turbo Profiler transfers 
them. 



TFREMOTE 






command-line 


Here are 1 


bhe TFREMOTE command-line options. You can start an 


options 


option with either a hyphen (-) or a slash (/). 


Table C.l 
TFREMOTE command-line 


Option 


What it does 


options 








-? 


Displays a help screen 




-h 


Displays a help screen 




-rs1 


Slow speed, 9600 baud 




-rs2 


Medium speed, 40 Kbaud 




-rs3 


High speed, 115 Kbaud (default) 




-rpl 


Port 1, (COMl) (default) 




-rp2 


Port 2, (COM2) 




-w 


Writes options to executable program file 



Started with no command-line options, TFREMOTE uses the 
default port and speed built into the executable program file 
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(COMl and 115 Kbaud), unless you've changed them with the -w 
option. 

You can make TFREMOTE's command-line options permanent by 
writing them back into the TFREMOTE executable program 
image on disk. To do this, specify -w, along with the other 
options you want to make permanent, on the command line. 
TFREMOTE prompts for the name of the executable program to 
write to; when you enter a new (nonexistent) executable file name, 
TFREMOTE then creates the file. If you press Enter, it overwrites 
the currently running program (TFREMOTE). 

Here's an example. If you type this command line at the DOS 
prompt, 

tfremote -w -rs2 -rp2 

Enter the name of the program to modify: tf rmt40k. exe. 
TFREMOTE will create a copy of TFREMOTE.EXE named 
TFRMT40K.EXE, where the default speed is 40 Kbaud (-rs2) and 
the default port is COM2 (-rp2). 

For a list of all TFREMOTE.EXE command-line options available, 
type this at the DOS command hne: 

TFREMOTE -h 

If you are running on DOS version 3.0 or later, the prompt 
indicates the path and file name from which you executed 
TFREMOTE. You can accept this name (press Enter), or enter a 
new executable file name. 

If you're using DOS 2.xx, you must supply the full path and file 
name of the executable program. 



Getting it all to work 



Because the remote profiling setup involves two different 
computers and a cable between them, you might run into 
difficulty getting everything to work together. 

If you experience problems, try these troubleshooting techniques: 

1. Check your cable hookups. 

2. Try running the link at the slowest speed (use the -rsl 
command-line option when starting up both TFREMOTE and 
TPROF). 
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3. If it works OK using -rs1, go on to try -rs2 (the middle 
speed). 

Some hardware and cable combinations don't always work 
properly at the highest speed. If you can only get remote profiling 
to work at a lower speed, consider trying a different cable or 
different computers. 



TFREMOTE 
messages 



Here is a list of the messages you might receive when you're 
working with TFREMOTE. 



nn bytes downloaded 

TFREMOTE is sending a file to the remote system. This message 
shows the progress of the file transfer. At the highest link speed 
(115 Kbaud), transfer speed is about UK per second. 

Can't create file 

TFREMOTE can't create a file on the remote system. This can 
happen if there isn't enough room on the remote disk to transfer 
the executable program across the link. 

Can't modify exe file 

You specified a file name to modify that is not a valid copy of the 
TFREMOTE utility. You can only modify a copy of the 
TFREMOTE utility with the -w option. 

Can't open exe file to modify 

TFREMOTE can't open the file name you specified to be modified. 
You have probably entered an invalid or nonexistent file name. 

Download complete 

Your file has been successfully sent to TFREMOTE. 

Download failed, write error on disk 

TFREMOTE can't write part of a received file to disk. This usually 
happens when the disk fills up. You must delete some files before 
TFREMOTE can successfully download the file. 
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Enter program file name to modify 

If you are running on DOS version 3.0 or later, the prompt 
indicates the path and file name from which you executed 
TFREMOTE. You can accept this name (press Entef), or enter a 
new executable file name. 

If you're running DOS version 2.xx, you must supply the full path 
and fQe name of the executable program. 

Interrupted 

You pressed Ctrl-Break whUe waiting for communications to be 
established with the other system. 

Invalid command line option 

You gave an invalid command line option when you started 
TDRF from the DOS command hne. 

Linic broken 

The program communicating with TFREMOTE has stopped and 
returned to DOS. 

Link established 

A program on the other system has just started to communicate 
with TFREMOTE. 

Loading program name from disk 

Turbo Profiler has told TFREMOTE to load a program from disk 
into memory in preparation for profiling. 

Program load failed, EXEC failure 

DOS could not load the program into memory. This can happen if 
the program has become corrupted or truncated. Delete the pro- 
gram file from the remote system's disk: This forces Turbo ProfQer 
to send a new copy over the link. If this message happens again 
after deleting the file, you should relink your program using 
TLINK on the local system and try again. 

Program load failed; not enough memory 

The remote system doesn't have enough free memory to load the 
program you want to profile. This only happens with very large 
programs, because TFREMOTE only takes about 15K of memory. 
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Program load failed; program not found 

TFREMOTE could not find the program on its disk. This should 
never happen since Turbo Profiler downloads the program to the 
remote system if TFREMOTE can't find it. 

Program load successful 

TFREMOTE has finished loading the program Turbo Profiler 
wants to profile. 

Reading file name from Turbo Profiler 

This appears on your remote screen so that you know when a 
remote file is being sent to Turbo Profiler. 

Unknown request: message 

TFREMOTE has received an invalid request from the local system 
(where you're running Turbo Profiler). If you get this message, 
check that the link cable is in good working order. If you keep 
getting this error, try reducing the link speed (use the -rs 
command-line option). 

Waiting for handshake (press Ctrl-Break to quit) 

TFREMOTE has started and is waiting for a program on the local 
system to start talking to it. To return to DOS before the other 
system initiates communication, press CW-Break. 
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Virtual profiling on the 80386 processor 

Turbo Profiler lets you use the full power of systems that have the 
80386 processor. Virtual profiling lets the program you're 
profiling use the full address space below 640K, just as if no 
profiler were loaded. (Turbo Profiler is loaded into extended 
memory, above the 1MB address point.) 

You profile exactly as you would normally use Turbo Profiler, 
except that your program loads and runs at exactly the same 
address that it does when ifs not being profiled. This is extremely 
useful both for profiling programs that are large, and for finding 
bugs that go away if the program is loaded higher in memory, as 
it is when it is being profiled normally. 

Virtual profiling also lets you watch for reads or writes to arbi- 
trary memory or I/O locations, aU at full or nearly fuU processor 
speed. This gives you some of the power of a hardware profiler at 
no additional cost. 

Equipment required for virtual profiling 

You must have a computer based on the 80386 or 80486 processor 
in order to use the virtual profiler. You must also have 700K of 
available extended memory. If you have used up your extended 
memory for RAM disks, caches, and so forth, you may want to 
make a special CONHCSYS or AUTOEXEC.BAT file that 
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removes some of these programs when you want to use virtual 
profiling. 

Installing the virtual profiler device driver 

Before starting the virtual profiler, you must make sure that you 
have installed its device driver, TDH386, in your CONFIG.SYS 
file. (TDH386 is included in the Turbo Debugger package.) Do this 
by including a line similar to the following in CONFIG.SYS: 

DEVICE = TDH386.SYS 

If you have placed the TDH386.SYS device driver somewhere 
other than in the root directory, make sure that you include that 
directory path as part of the device driver file name. 

Normally, the virtual profiler lets you have up to 256 bytes of 
DOS environment strings. If this is not enough, or if you don't 
need that much and would like to conserve as much memory as 
possible, use the -e option in CONFIG.SYS to set the number of 
bytes of environment. For example, 

DEVICE = TDH386.SYS -e2000 

reserves 2000 bytes for your DOS environment variables. 

Starting the virtual profiler 

You start the virtual profiler much as you would normally start 
Turbo Profiler, with a command line like this: 

TF386 [options] program [program options] 

In other words, you simply enter TF386 instead of tprof. TF386 
then takes care of finding the Turbo Profiler executable program 
and loading it into extended memory. 

If you have other programs or device drivers that use extended 
memory, such as RAM disks, caches, or whatever, you must tell 
TF386 how much extended memory to set aside for these other 
programs. Do this by using the -e command-line option. FoUow 
the -e with the number of kilobytes (K) of extended memory used 
by other programs. For example, 

TF386 -e512 myprog 
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This command line informs TF386 that you want to reserve the 
first 512K of extended memory for other programs. (It isn't neces- 
sary to do this if your machine supports the XMS standard; TF386 
allocates memory from the XMS device driver if one is present.) 

Since you probably always reserve the same amount of extended 
memory for other programs, TF386 gives you a way to perma- 
nently set the amount of extended memory to reserve. Use the -w 
option with the -e option to specify that you want the -e value to 
be permanently set in the TF386 executable program file. 

You'll then be prompted for the name of the executable program. 
If you are running on DOS 3.0 or later, the prompt indicates the 
path and file name that you executed TF386 from. You can accept 
this name by pressing Enter, or you can enter a new executable file 
name. The new name must already exist and be a copy of the 
TF386 program that you have already made. 

If you are running on version 2.x of DOS, you will have to supply 
the full path and file name of the TF386 executable program. 

Here is a complete list of command-line options for TF386.EXE: 

-? Accesses help on TF386. 

-e#### Specifies the number of kilobytes of extended 

memory being used by other programs or by the 
program you're profiling. (You don't need this 
option if your system supports the XMS 
standard.) 

-!#### Enables EMS emulation through paging (in 
extended memory) and sets the page frame 
segment to #### (in hex). The last three digits 
must be 000 (like COOO or EOOO). Note that this 
option only applies to Turbo Profiler's EMS calls. 
If you don't use this option when you load TF386, 
TF386 will not be able to use EMS. 

-f- Disables EMS emulation (presumably to override 

a previous command-line option). 

-w Modifies TF386.EXE with the new default value 

of -e or -f . You can enter a new executable file 
name that does not already exist, and TF386 will 
create the new executable file. 
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Note that TF386.EXE options must appear first in the 
command line before any Turbo Profiler options or the 
program name. For example, 

TF386 -el024 -fDOOO -w 

reserves 1024K of extended memory, enables EMS 
emulation with a page frame of DOOO, and modifies 
TF386.EXE with these values. 

For a list of all the command-line options available for 
TF386.EXE, just type TF386 -? or TF386 -h and press Enter. 

Note: If you have an 80386-based machine and want to read 
the command-line options for TF386.EXE, TDH386.SYS 
must be loaded. 

Differences between normal and virtual profiling 

Most things work exactly the same whether you are 
profiling nornvally or using the 80386 virtual profiling 
capability. The following items behave differently: 

■ When you use the File 1 DOS Shell command to run a DOS 
command, the program you're profiling is never swapped 
to disk. This means you may not always have enough 
memory to run other programs from the DOS prompt. 

■ Your program can use nearly all of the 80386 instructions, 
with the exception of the privileged protected-mode 
instructions: CLTS, LMSW, LTR, LGDT, LIDT, LLDT. 

■ Even though you can use all the 80386 extended address- 
ing modes and 32-bit registers during virtual profiling, 
you can't access memory above the 1MB point. If you try 
to do so, an exception interrupt wiU be generated, and 
Turbo Profiler will regain control. 

■ You can't use virtual profiling if you're already running a 
program or device driver that uses the virtual and 
protected modes of the 80386 processor. This includes pro- 
grams such as: 

• DesqView operating environment 

• Microsoft Windows-386 operating environment 

• QEMM.SYS, the QuarterDeck EMS simulator 

• CEMM.SYS Compaq EMS simulator 
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If you normally use one of these or similar programs, you 
will have to stop them or unload them before using TF386. 



TF386 error messages 



TF386 generates one of the following messages when it can't 
start, and then returns to the DOS prompt. You must correct 
the condition before you can start TF386 successfully. 

TF386 error: 80386 device driver missing or wrong version 

You must install the TFH386.SYS device driver in your 
CONHCSYS file before you invoke TF386 from the DOS 
command Hne. 

TF386 error: Can't enable tlie A20 address line 

TF386 can't access the memory above 1MB. This may 
happen if you're running on a system that is not exactly IBM 
compatible. 

TF386 error: Can't find TPROF.EXE 

TF386 could not find T.EXE. 

TF386 error: Couldn't execute TPROF.EXE 

TF386 could not run TPROF.EXE. 

TF386 error: Environment too long; use -e#### swltcii witli 
TFH388.SYS 

You need to change the -e option as described on page 160. 

TF386 error: Not enougii Extended l\/Iemory available 

TF386 ran out of memory. You need to get more memory for 
your machine or free up memory (by reducing a RAM disk, 
for example). 

TF386 error: Wrong CPU type (not an 80386) 

You are not nmning on a system with an 80386 or 80486 
processor. 

The following errors might occur if you're trying to modify 
TF386 with the -w option: 

TF386 error: Cannot open program file 

TF386 error: Cannot read program file 



Appendix D. Virtual proWing on the 80386 processor 1 63 



TF386 error: Cannot write program file 

TF386 error: Program file corrupted or wrong version 



TDH386.SYS error messages 



There are only two possible error messages associated with 
the TFH386.SYS driver: 



Wrong CPU type: TDH386 driver not installed 
Invalid command line: TDH386 driver not installed 
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Prompts and error messages 



Turbo Profiler displays messages and prompts at the current 
cursor location. This chapter describes the prompts and error and 
information messages Turbo Profiler generates. 

We tell you how to respond to both prompts and error messages. 
All the prompts and error messages are Hsted in alphabetical 
order, with a description provided for each one. 



Turbo Profiler prompts 



Turbo Profiler displays a prompt in a dialog box when you must 
supply additional information to complete a command. The 
prompt describes the information that's needed. The contents may 
show a history list (previous responses) that you have given. 

You can respond to a prompt in one of two ways: 

D Enter a response and accept it by pressing Enter. 

B Press Esc to cancel the dialog and return to the menu command 
that opened it. 

Some prompts only present a choice between two items (like 
Yes/No). You can use Tab to select the choice you want and then 
press Enter, or press Yor N directly. Cancel the command by press- 
ing Esc. 

For a more complete discussion of the keystroke commands to use 
when a dialog box is active, refer to Chapter 4. 
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Here's an alphabetical list of all the prompts ai\d messages 
generated by dialog boxes: 

Enter code label to position to 

Enter the address you wish to examine in the Code pane. The 
Code pane shows the disassembled instructions at the specified 
address. 

Enter command line arguments 

Enter the command-line arguments for the program you're 
profiling. You can modify the current command-line arguments 
or enter a new set. 

You will then be prompted whether you want to reload your 
program from disk. Some languages or programs, such as 
programs written in C, require you to reload the program before 
the arguments take effect. 

Enter file name to restore areas from 

Enter the name of the file to restore areas from. If you specify an 
extension to the file name, it will be used. Otherwise the 
extension .TEA will be used. 

Enter file name to restore from 

Enter the name of the file to restore the statistics to. If you specify 
an extension to the file name, it will be used. Otherwise the 
extension .TFS wiU be used. 

Enter file name to save areas to 

Enter the name of the file to save the current areas to. If you 
specify an extension to the file name, it wiU be used. Otherwise 
the extension .TEA will be used. 

Enter file name to save to 

Enter the name of the file to save the current statistics to. If you 
specify an extension to the file name, it will be used. Otherwise 
the extension .TK wiU be used. 

Enter file name to write to 

Enter the name of a file to send the report to. If the file already 
exists, it wUl be overwritten. 

Enter name of configuration file 

Enter the name of a configuration file to read or write. If you are 
reading from a configuration file, you can enter a wildcard mask 
and get a list of matching files. 
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Enter maximum number of areas 

Enter the maximum number of areas that you wish to divide the 
program into. Since each area takes up some memory, try to set 
the maximimn to as low a value as is reasonable. 

Enter maximum symboi width to display 

Enter the width for symbol names on reports and for symbol 
names displayed in windows. 

Enter new directory 

Enter the new drive and /or directory name that you want to 
become the current drive and directory. 

Enter new iine number 

Enter a new line number to position the text file to. The first line 
in the file is line 1. If you specify a line number that is greater than 
the last line in the file, the file is positioned to the last line. 

Enter new page helghit 

Enter the number of lines on a page to be sent to the printer or a 
disk file. A normal 11-inch sheet of paper has 66 lines. 

Enter new page width 

Enter the width of the page for reports sent to the printer or a disk 
file. A normal sheet of paper has 80 columns. 

Enter program name to ioad 

Enter the name of the program to load. If the program has the 
.EXE extension, you don't have to specify it; if the program has 
any other extension, you must supply it. 

If you supply a wildcard specification or accept the default *.EXE, 
a list of matching files is displayed for you to select from. 

Enter program run count 

Enter the number of times that you want to run the program and 
accumulate performance statistics. The more times you run your 
program, the more accurate the clock tinnings will be. 

Enter routine name to add 

Enter the name of the function you wish to include, exclude, or 
set. 

Enter search string 

Enter a character string to search for. You can use a simple wild- 
card matching facility to specify an inexact search string; for 
example, use * to match zero or more of any characters, and ? to 
match any single character. 
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Enter source directory list 

Enter the directory or directories to search for source files. 

If you want to enter more than one directory, separate the 
different directory paths with a space or a semicolon 0). These 
directories will be searched, in the order that they appear in this 
Ust, for your source files. 

Enter tab column spacing 

Enter a number between 1 and 32 that specifies how far apart tab 
columns will be when Turbo Profiler displays files in a Module 
window. 

Usually, you use tabs for each level of control-structure nesting in 
your source code. If your source code has deeply nested control 
structures, you can use a smaU tab value (like 2 or 3) so that your 
source doesn't disappear off the right side of Module windows. 

Pick a caller 

Pick a routine from the list of caUers. You will then be positioned 
to that routine in the vmidow that you picked from the previous 
menu. 

Pick a metliod name 

You have specified a routine name that can refer to more than one 
method in an object. Pick the correct one from the list presented, 
with the arguments you want. 

Pick a module 

Select a module name to view in the Module window. You are 
presented with a Ust of aU the modules in your program. Either 
use the cursor keys to move to the desired module, or start typing 
the name of the module. As you type the module name, the 
highlight bar will move to the first module that matches the 
letters you typed. When the highlight bar is on the desired 
module, press Enter. 

Pick a source file 

Pick a new source file to display in the Module window. The list 
shows all the source files that make up the module. 

Pick a symbol name 

Pick a symbol from the list of displayed symbols. You can start to 
type a name, and you will be positioned to the first symbol, start- 
ing with what you have typed so far. 
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Pick a window 

Pick the window you want to make the active window by moving 
the highlight bar to it and pressing Enter or choosing the OK 
button. 

You can close a window by moving the highlight bar to that 
window name and pressing the Del or Ctrl-Y. 

Picic interrupt 

Pick an interrupt from the list of interrupts built in to Turbo 
Profiler. 



Turbo Profiler error messages 



Turbo ProfQer uses error messages to tell you about things you 
haven't quite expected. Sometimes the command you have issued 
cannot be processed. At other times the message warns that 
things didn't go exactly as you wanted. 

Error messages are normally accompanied by a beep. You can 
turn off the beep in the customization program, TFINST. 

Already recording, do you want to abort? 

You are already recording a keystroke macro. You can't start 
recording another keystroke macro until you finish the current 
one. Press V to stop recording the macro; A/ to continue recording 
the macro. 

Ambiguous symbol symbol name 

You have entered a member function or data item name and 
Turbo Profiler can't tell which of the multiple instances of this 
member you mean. 

This can happen when a member name is duplicated in two 
multiply inherited classes. Use the classname:: override to name 
explicitly the member you want. 

Bad configuration file name 

You have specified a nonexistent file name with the -c 
command-line option when you started Turbo Profiler. The built- 
in default configuration values are used instead. 

Bad interrupt number entered 

You have entered an invalid interrupt number. Valid interrupt 
numbers are 9 to PP. 
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Bad line number line number 

The line rnnnber that you have entered does not exist or does not 
correspond to a line of source code. 

You can specify only source line numbers that are in functions, 
not those outside functions. 

Bad module name module name 

The module name that you have entered does not exist. 

Can't execute DOS command processor 

Either there was not enough memory to execute the DOS 
command processor, or the command processor could not be 
foimd (the COMSPEC environment variable is either absent or 
incorrect). Make sure that the COMSPEC environment variable 
correctly specifies where to find the DOS comniand processor. 

Can't open printer 

There was an error sending to the printer. Check that the printer 
is online and not out of paper. 

Can't swap user program to disk 

The program being profiled could not be swapped to disk. There 
is probably not enough room on the disk to swap the program. 
You will not be able to edit any files or execute DOS commands 
until some more room is made available. 

Clear all existing statistics 

When you change the clock tick rate, all existing statistics become 
meaningless and must be cleared. If you do not confirm the 
statistics clear, the clock speed will not be changed. 

Edit program not specified 

You tried to use the Edit local menu command from a Module or 
Disk File window, but you cannot edit the file because Turbo 
Profiler does not know how to start your editor. 

Use the configtiration program TFINST to specify an editor. 

Error reading areas file 

An error occurred while you were restoring the areas. Make sure 
that the disk is ready. 

Error reading statistics file 

An error occurred while you were restoring the collected 
statistics. Make sure that the disk is ready. 
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Error saving configuration 

Your configuration could not be saved to disk. The disk might be 
full, or there might be no more free directory entries in the root 
directory. 

You can use the File I DOS SheU command to go to DOS and 
delete a file or two to make room for the configuration file. 

Error swapping in user program, program reioaded 

An error occurred while you were reloading your program that 
was swapped to disk. This usually means that the swap file was 
accidentally deleted. 

You will have to reload your program using the Rim I Program 
Reset command before you can continue profiling. 

Error writing areas f iie 

An error occurred while you were writing to the area file that 
stores information on marked areas in your program. Your disk is 
probably full. 

Make sure that the disk is ready and that there is enough room on 
the disk. 

Error writing statistics file 

An error occurred while you were writing to the statistics file that 
stores your program statistics. Your disk is probably full. 

Make sure that the disk is ready and that there is enough room on 
the disk. 

Help file TFHELP.TFH not found 

You asked for help but the disk file that contains the help screens 
could not be found. Make sure that the help file is in the same 
directory as Turbo Profiler. 

Invalid areas file 

The file name you specified to restore areas from is not formatted 
correctly. Make sure you specified a file name that was created by 
Turbo Profiler. 

invalid statistics file 

The file you specified to restore statistics from has an invalid 
format. Make sure the file name you specified was created using 
the Statistics I Save command. 
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Maximum number of areas has been reached 

There is no more room to add areas. Use the Options I Number of 
Areas command to increase the amount of memory set aside for 
areas. 

Maximum number of interrupts being monitored 

You can't watch any more interrupts; you have akeady told 
Turbo Profiler to watch as many interrupts as it is capable of 
doing. You will have to use the local menu Remove command to 
remove an existing interrupt before you can add any more. 

No heip for this context 

You pressed F1 to get help, but Turbo Profiler could not find a 
relevant help screen. Please report this to Borland technical 
support. 

No caiier information for this function 

The highlighted line is in a function for which no caller 
information was collected. Caller information is collected only if 
it is explicitly requested. 

No fiie name was given 

You have indicated that you wish to output a file, but you have 
not specified a file name. You must either specify a file name or 
switch to another output location before you can leave the dialog. 

No moduies with statistics 

There are no modules with any statistics collected, so there is 
nothing to print. 

No previous search expression 

You have used the Next command from the local menu of a text 
pane, without previously issuing a Search command. First use 
Search to specify what to search for, then use Next to look for 
subsequent instances. 

No program ioaded 

You tried to issue a command that requires a program to be 
loaded. There are many commands that can only be issued when 
a program is loaded, for example, the commands in the Run 
menu. Use the File I Open command to load a program before 
issuing these commands. 

No source fiie for module module name 

The source file cannot be found for the module that you wish to 
view. The source file is searched for first in the current directory, 
and then in any directories specified in the configuration file and 
then in any directories specified by the coiim:mnd line -sd option. 
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Not a code address 

You have entered an address that is not a code address in your 
program. You can only set profiling areas on code addresses. 

Not enough memory for selected operation 

You issued a command that has to create a window, but there is 
not enough memory left for the new window. You must first 
remove or reduce the size of some of your windows before you 
can reissue the command. 

Not enough memory to load program 

Your program's symbol table has been successfully loaded into 
memory, but there is not enough memory left to load your pro- 
gram. If your system has EMS memory, make sure that Turbo 
Profiler is set to use it for the symbol table. You can use TFEvJST to 
set this option. 

If you don't have EMS or your program doesn't load even with 
EMS, you can hook two systems together and run Turbo Profiler 
on one system and the program you're analyzing on the other. See 
Appendix C for more information on how to do this. 

Not enough memory to load symbol table 

There is not enough room to load your program's symbol table 
into memory. The symbol table contains the information that 
Turbo Profiler uses to show you your source code and program 
variables. If you have any resident utilities consuming memory, 
you may want to remove them and then restart Turbo Profiler. 
You can also try making the symbol table smaller by having the 
compiler generate debug symbol information only for those 
modules you are interested in analyzing. 

When this message is issued, your program itself has not yet been 
loaded. This means you must free enough memory for both the 
symbol table and your program. 

Overlay not loaded 

You have attempted to examine code in an overlay that is not 
loaded into memory. You can only examine code for overlays that 
are already in memory. 

However, you can still look at the source code for a module in a 
Module window. 

Overwrite existing macro on selected key 

You have pressed a key to record a macro, and that key already 
has a macro assigned to it. If you want to overwrite the existing 
macro, press V; otherwise, press N to cancel the command. 
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Overwrite file namel 

You have specified a file name to write to that ahready exists. You 
can choose by entering V to overwrite the file, replacing its 
previous contents, or you can cancel the command by entering A/ 
and leave the previous file unchanged. 

Path not found 

You entered a drive and directory combination that does not exist. 
Check that you have specified the correct drive and that the direc- 
tory path is spelled correctly. 

The current drive and directory are left as they were before you 
issued the command. 

Path or file not found 

You specified a non-existent or invalid file name or path when 
you were prompted for a file name to load. If you do not know 
the exact name of the file you want to load, you can pick the file 
name from a list by pressing Enler when the dialog box first 
appears. 

Possibly you entered wildcard specification that is not valid. Only 
the normal DOS wildcard characters * and ? can be used. 

Premature end of string in symbol name 

The symbol name that you have entered is incomplete. If you 
specify a module name, it must be followed by either a line 
number or local symbol name. 

Press icey to assign macro to 

Press the key that you want to assign the macro to. Then, press 
the keys to do the command sequence that you want to assign to 
the macro key. The command sequence will actually be per- 
formed as you type it. To end the macro recording sequence, 
press the key you assigned the macro to. This macro will be 
recorded on disk along with any other keystroke macros. 

Press key to delete macro from 

Press the key for the macro that you want to delete. The key will 
then be returned to its original pre-macro function. 

Program already terminated, Reload? 

You have attempted to run or step your program after it has 
already terminated. If you choose Y, your program wiU be 
reloaded. If you choose N, your program will not be reloaded, and 
your run or step command wiU not be executed. 
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Program does not have overlays 

The program you are profiling does not have any overlays, so you 
can't open an Overlay window. 

Program has invalid symbol table 

The program that you wish to load has a symbol table with an 
invalid format. Re-create your .EXE file and reload it. 

Program has no symbol table 

The program you want to analyze has been successfully loaded, 
but it does not contain any debug symbol information. Relink the 
program so that it has a symbol table. 

Program linked with wrong linker version 

The program you wish to load was linked with an old version of 
the linker. You must use the latest version of the linker for 
profiling programs. 

Program not found 

The program you wish to load does not exist. Check that the 
name you supphed to the File I Open command is correct and that 
you suppHed a file name extension if it is different from .EXE. 

Program out of date on remote, send over link? 

You have specified a program to analyze on the remote system, 
but it either does not exist on the remote, or the file is newer on 
the local system than on the remote system. 

If you press V, the program is sent across the link. If you press N, 
the program is not sent, and the File I Open command is aborted. 

You'll usually respond with Y. If you are running the link at the 
slowest speed (using the -rsl command-line option), you might 
want to abort the command with A/ and transfer the file to the 
remote system using a floppy disk. 

Reload program so arguments take effect? 

With most programs, you must reload after changing their 
arguments. Always press /at this prompt, unless you know what 
you're doing. 

When you press V, a Run I Program Reset command is 
automatically performed for you. 

Reload program so new area count takes effect? 

In order for Turbo Profiler to reallocate the memory used for 
statistics areas, your program must be unloaded from memory 
and then reloaded and executed from the beginning again. 
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Press y to make this happen, or press N if you can wait for the 
next manual program load for the new area size to take effect. 

Run out of space for keystroke macros 

There is not enough memory to record all your keystroke macro. 

Search expression not found 

The specified text string or byte list is not present in the file. Since 
the search proceeds forward from the current cursor position, you 
should return to the top of the file via the Ctrl-PgUp hot key, then 
repeat the search. 

Symbol name not found 

The s)Tnbol name that you supplied is not a valid symbol name. 

Symbol not a routine name 

The symbol name that you supplied is not a valid name of a 
routine. 

Symbol not found 

You have entered an expression containing an invalid symbol 
name. A vaHd symbol name consists of either: 

Da global symbol name. 

2) a module name, followed by #, followed by a local symbol 
name. 

3) a module name, followed by a #, followed by a decimal line 
number. 

Symbol SymbolName Is a data symbol 

The program symbol name that you have entered refers to data in 
the program, and not to code. You can only specify code 
addresses to be profiled. 

Syntax error In symbol SymbolName 

You have entered an invalid symbol name. A valid S5mibol name 
consists of either: 

Da global symbol name. 

2) a module name, followed by a #, followed by a local symbol 
name. 

3) a module name followed by a # followed by a decimal line 
number. 

Tab width must be between 1 and 32 

You have entered an invalid value for the tab width. Tab columns 
must be at least 1 colinrm wide, but no more than 32 columns. 
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Too many files match wildcard mask 

You specified a wildcard file mask that included more than 100 
files. Only the first 100 file names are displayed. 

Video mode switched while flipping pages 

You have started Turbo Profiler with a display updating mode 
that does not aUow display pages to be saved, and the program 
that you are profiling has switched into a graphics mode. 

Turbo Profiler has changed the display mode back to text display, 
so the screen contents of the program you are profiling have been 
lost. 

To avoid this, start Turbo Profiler with display-swapping enabled 
(-ds command-line option). 
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problems with 763 



-f option (TF386 virtual profiler) 767 
far heap 

profiling and 38 
Fast Screen Update check box (TFINST) 743 
features 7 

environment 63 
File 

command 85, 86 
dialog box 86 
menu 73 
files 
access 
monitoring 45 
profiling purposes and 48 
tracking 78 
activities 

displaying 57 
area 

problems with 777 
AUTOEXEC.BAT 
virtual profiling and 760 
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configuration See configuration files 
disk 

problems with 171 
disks 

problems with 170 
distribution 

list of 3 
executable program 167 

TF386 virtual profiler and 161 
HELPMEI.DOC 145 
information on 76 
loading 27 

cancelling 74 
opening 

problems with 136, 174 
wildcard masks and 177 
opening and loading 73 
overwriting 174 
README 3 
source 

current routine 106 

directories 85, 125 

inspecting 94 

list of 85 

loading 168 
problems with 172 

options 135 

setting directory path 145 

viewing 88 

viewing with statistics 18 

where searched for 42 
statistics See statistics 
SWAP.$$$ 171 
TDH386.SYS 160, 162 
.TFA See .TEA files 
.TFS See .TFS files 
TPROF.EXE 149 
Files option 45 

Statistics menu 112 
Files window 56, 78, 98, 99 
Filter command 49, 56, 89 
filters See statistics 
Follow command 

Disassembly (CPU) window 108 
43/50-line mode 
disabling 136 
43- and 50-line displays 124 



frequency collisions 

solving 37 
Frequency option 89, 94 
Full Graphics Saving check box (TFINST) 743 
function-entry area markers See area markers, 

function 
functions See also routines 

C and Pascal 
terminology 5 

G 

Get Info command 76 
global menus See menus 
global symbols 

list of available 704 
Goto command 

Disassembly (CPU) window 108 

Module window 81 
Graph option 707 
graphics See also graphics adapters 

color tables 747 

display buffer, saving 743 

image 
saving 736 

palette 
EGA 
saving 735 

problems with 
snow 743 
graphics adapters 747, See also graphics 

display options 743 

display pages 744 

EGA 743 

Hercules 743 

monochrome text-only 748 

VGA 743 
graphs 

file activity 707 

H 

-h option (help) 733, 755 
hardware 
adapters 
display options 
setting 743 
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requirements 
TF386 virtual profiler 159 
hardware requirements 3 
heap See also memory 
far 

profiling and 38 
modifying 134 
size 
default 734 
Help 

button 69 
menu 129 
window 
closing 129 
keywords in 129 
opening 129 
help 

accessing 129 

problems with 1 71, 1 72 
command-line options 
TF386 virtual profiler 162 
TFINST 149 
help on help 130 
index 129 
keywords 129 
option 133 
previous topic 129 
status line 68 
TFREMOTE 755 
Help on Help command 130 
HELPMEI.DOC 

setting directory path for 145 
Hercules graphics adapter 148 
History List Length input box (TFINST) 145 
history lists 70 
choosing from 75 
length, setting 145 
History option 96 
hot keys 

dialog boxes 65 
enabling 146 
Esc 69 
menus 65 
using 65 

I 

-i option (process ID switching) 134 



I/O 

disk 
active analysis and 51 
passive analysis and 51 

keyboard 
profiling and 41 
IBM 

graphic characters 
printing 16 
IBM PC Convertible and NMI 146 
Iconize/ Restore command 127 
icons 

restoring 727 
identifiers 

Turbo C 57 

imderscores and 91 
Ignore Case of Symbol check box (TFINST) 747 
Immediate Callers option 

Area Options dialog box 703 

Stack Trace dialog box 84 
Index command 729 
input boxes 

DOS Shell Swap Size (TFINST) 747 

History List Length (THNST) 745 

Tab Size 
TFINST 744 
Inspect Areas command 702 
Inspect command 94, 96 
INSTALL.EXE 3 
installation 3 

TDH386.SYS device driver 160 

TF386 virtual profiler 759 

TFREMOTE (remote profiling utility) 752 
instructions 

current 
pointer 
returning to 705 

displaying 709 

pointer 
address of 709 
integrated environment 63-130 

DOS screen and 723 
interrupts 

adding to statistics collection 97 

amount of time in 97 

display formatting options 98 

exception, TF386 virtual profiler and 762 
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execution timing and resource monitoring 

and 48 

monitoring 45 

names 97 

NMI 146 

number of calls to 97 

passive analysis and 51, 52 

pick list 98 

removing from statistics collection 98 

removing from window 57 

statistics 97 

subroutines 97 
Interrupts option 45 

Statistics menu 112 
Interrupts window 56, 78, 96 
I/O 

options 145 

watching, TF386 virtual profQer and 159 

K 

keyboard 

choosing buttons with 69 
choosing commands with 64 
input 
profiling and 41 
keys 

cursor-movement 
TFINST 140 
keystrokes 
recording 176 
problems with 169 
keywords 

Help windows 129 

L 

labels 

moving cursor to 80 
LCD screens 148 
Line command 80 
line counts 

algorithm analysis and 48 

program verification and testing and 48 
line numbers 167 
lines 

jumping to 57 

marking 10, See area markers 



moving cursor to 80 
Lines in Routine command 

Add Areas 81 

Remove Areas 82 
link 

remote 
speed 135 
Link Speed radio buttons (TFINST) 747 
list boxes 71 

file names 75 

searching incrementally 129 
Load command 

cancelling 74 
local menus See menus 
Local Module option 105 
local system 

remote profiling and 151 
Longest option 88 
loops 

optimizing 58, 59 

M 

-m option (modify heap) 134 
macros 121, 121-123 

creating 121, 123 

deleting 123 

recording 
problems with 173, 176 

removing 123 

saving 722 

stop recording 723 
Macros command 727 
magnitude bar 72 
maps 

memory 
profiler use 38 
markers 

area See area markers 
math coprocessors See numeric coprocessors 
Maximum Areas command / 13 
memory 755, 745, See also heap 

accessing 
TF386 virtual profiler and 162 

addresses 
high 759 

allocation 
problems with 775 
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TF386 virtual profiler and 160 

EMS See EMS 

error messages 151 

heap 
size 134 

overlays and 95 

problems with 1 73 

profiler use of 38 

stop and start points and 45 

usage 77 

watching 
TF386 virtual profiler and 159 
menu bar See menus 
menus 

accessing 63 

customizing 141 

hot keys 65 

local See menus, pop-up 

opening 64 

Options 121-127 

pop-up 64 

TFINST 140 

with arrows (►) 64 

with ellipsis marks {...) 64, 68 
Menus command (TFINST) 141 
Microsoft 

Windows 162 
Microsoft mouse 

compatibility 63 
Miscellaneous Options dialog box (TFINST) 146 
Mixed command 

Disassembly (CPU) window 109 
Mode for Display menu (THNST) 147 
modem 

remote profiling and 152 
ModifyTPROF.EXE command (TRNST) 149 
Module command 84, 90 

Print menu 119 

Routines window 106 
Module option 89 
Module window 78, 79 

area markers 
removing 91 

Execution Profile window and 87 

printing from 14 

source code and 
inspecting 94 



modules 
current 

statistics 56 
defined 5 
loading 168 
viewing 
problems with 1 72 
source code in 167 
Modules with Source command 
Add Areas 81 
Remove Areas 82 
monitors See displays 
mouse 

choosing buttons with 69 
choosing commands with 64 
support 63 
disabling/enabling 134, 146 
Mouse Enabled check box (TFINST) 146 

N 

Name input box 74 

Name option 89 

NEC MultiSpeed and NMI 146 

New Directory dialog box 76 

Next command 81, 127 

problems with 1 72 
Next Pane command 127 
NMI, systems using 146 
NMI Intercept check box (TFINST) 146 
No option 

Disassembly (CPU) window 109 
None option 

Area Options dialog box 103 

Stack Trace dialog box 84 
normal area markers See area markers, normal 
Normal option 103 
null modem cable 

remote profiling and 752 
numeric coprocessors 

profiling tutorial and 9 



.OBJ files 

Turbo C and 9r 
object-oriented programs 

expressions, problems with 169 
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profiling 52 
OK button 69 

OOP See object-oriented programs 
Open command 73 
Operation 

command 82, 83 

option 705 
optimizers 

profiling and 2 
options 145 

customizing 139 

display 142-144 
swapping 142 

input 145 

restoring 118, 126 

restoring defaults 149 

saving 125 

setting 10 
Options command 

Areas window 103 

Print menu 120 
Options menu 121, 121-127 

TFINST 145 
Origin command 

Disassembly (CPU) window 108 
OS Shell command 

TF386 virtual profiler and 162 
output 

to DOS 
viewing from IDE 128 

user 128 
overhead 

calculating 31 
Overlay command 57 
Overlay window 54 
overlays 

area size 136 

buffer management 
overlay event history and 54 

demonstration 95 

execution timing and resource monitoring 
and 45 

history 96 

memory and 95 

monitoring 45 

problems with 173 



profiling 

tips and techniques 54 
statistics 95 
demonstration 95 
Overlays option 45 

Statistics window 113 
Overlays window 56, 78, 95 
demonstration 95 



-p option (mouse support) 134 

palette See graphics 

panes 

next 127 
parameters See arguments 
Pascal 

functions 
terminology 5 

procedures 
terminology 5 

profiling 5 
passive analysis See also active analysis; 

profiling, analysis modes 

active analysis vs. 51 

caller information and 51 

disk I/O and 51 

execution counts and 51 

interrupts and 51, 52 

program execution time and 51 

setting 50 
Path for Source command 125 
paths 

call 
logging 36 
sorting 94 

setting 135 
Per Call option 88 
performance analyzer See profilers 
Permit 43/50 Lines check box (THNST) 143 
Pick a Caller dialog box 94 
Pick a Module dialog box 85, 89, 106, 1 19 
Pick command 98 
PLOST.C and PLOSTPAS.PAS 32 
pointers 

arrays and 58, 61 

instruction 
address of 109 
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current 
returning to 108 
pop-up menus See menus 
ports 
remote 

setting 135 
serial 147 
Previous command 

Disassembly (CPU) window 705, 109 
Previous Topic command 129 
PRIME4*.* 

listing 24 
PJUMEn*.* (example program) 8 
Print menu 119 

Printer Options radio buttons (TFINST) 146 
printing 

high versus standard ASCII 146 
Module window contents 14 
Printing Options dialog box 120 
procedures See functions 
Pascal 
terminology 5 
process ID switching 134 
Profile command 

Routines window 106 
Profile mode command ) 13 
profile report windows See windows, profile 

report 
profiling 

80386 processors 159-164 
analysis modes See also active analysis; 
passive analysis 
active 113 
choosing 48, 50 
compared 114 
current 77 
default 113 
passive 113 
control 

TF386 virtual profiler and 162 
defined 1 
end results 47 

type of statistics to collect for 48 
far heap and 38 
large programs 151, 159 

display modes and 143, 144 
object-oriented programs 52 



optimizers and 2 
passes 113 

preparing programs for 41 
program speed and 52 
refining the process 49 
remote 134, 151-158 

commands 152 

DOS version and 155 

hardware requirements 151 

local system 151 

remote system 151 

remote systems 
defaults, setting 147 

starting 154 

troubleshooting 155 

User Screen window and 152 

when to do 151 
resetting program 110 
sampler screen 15 
saving profiles 47 
slow programs and 52 
small programs 136 
speeding up 52 
starting 110 
steps 9, 40 
Profiling Options dialog box 50, 1 13 
program execution 

stopping 83 
Program Reset command 110 
program source windows See windows, 

program source 
Programming Pearls 7 
programs 144 
compiling 

for profiling 42 
current 76 
example 8 
execution speed 

profiling and 52 
execution time 

passive analysis and 51 
file access 

monitoring 45 
keyboard input 

profiling and 41 
loading 159, 167 

problems with 136, 172, 175 
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symbol tables and 173 
object oriented See object-oriented programs 
optimizing 57 
preparing for profiling 41 
profiling 

starting a run 110 

with no debug symbol information 175 

with out-of-date debug symbol 

information 175 
reloading 

problems with 171 
restructuring 

Callers window and 93 
running 

from DOS 162 

nonmaskable interrupts and 147 
size 

areas and 44 
slow 52 
source 

location 85 

viewing 78, 79 
speed 

statistics collection and 47 
stopping during a profiling session 43 
structure analysis 

statistics for 48 
swapping to disk 

problems with 170 
testing and verifying 

line-count information and 48 

statistics for 48 
timing 

statistics for 48 
unfamiliar 

studying 50 
prompts 

commands and 165 
dialog boxes 165-169 
responding to 165 
setting 145 
propagation of time 104 

Q 

Quarter Deck EMS simulator 162 
question mark (?) search wildcard 80 



quicksort 

bubble sort vs. 58 
Quit command 78 

TFINST 150 



-r option (remote profiling) 134, 153 
radio buttons 70 

Display Swapping 
THNST 142 

Link Speed (THNST) 147 

Printer Output (TFINST) 146 

Remote Link Port (THNST) 147 

Screen Lines 
TFINST 143 

User Screen Updating (TFINST) 144 
README file 3 
recursive routines 

when to use 60 
Refresh Desktop command 73 
registers 

80386 processor, virtual profiling and 162 
Remote Analyzing check box (TFINST) 147 
Remote Link Port radio buttons (TFINST) 147 
remote links 

defaults, setting 147 

problems with 175 
remote profiling See profiling, remote 
remote system 

remote profiling and 151 
Remove Areas command 82, 102 
Remove command 57, 91, 98 

current areas 56, 57 

interrupts 57 

Macros menu 123 

undoing 97 
report windows 

summary 39 
requirements 

hardware 3 

software 42 
resizing windows 18 
resonance 53 
resources 

monitoring 
statistics for 48 
Restore command 118 
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Restore dialog box 126 
Restore Options command 126 
Restore Standard command 73 
return points 

caution 35 
return statements 

area markers and 35 
Routine window 78 
routines See also functions 

accessing 
problems with 168 

active 
call stack and 35 

available 78 

calling other routines 
tracking 45 

calling sequence 78, 1 12 

combined clock and 46 

defined 5 

jumping to 5? 

marking See area markers 

optimizing 57, 60 

overhead 31 

recursive 
when to use 60 

reducing calls to 24 

timer data 46 
Routines in Module command 

Add Areas S/ 
Routines in Modules command 

Remove Areas 82 
Routines window 104 
Run command 110 
Run Count command / 13 
Run menu 110 
rimning 

TF386 virtual proffler 159-164 

TFINST 139-150 



-s option (source code and symbols) 135 
sample programs 

PRIMEn*.* 8 
sampling 

coimting vs. 37 
Save command 117 



Save Configuration dialog box 19, 125 
Save Configuration File command (TFINST) 

149 
Save dialog box 117 
Save menu (TFINST) 149 
Save Options command 125 
Screen command (TFINST) 142 
Screen Lines command 124 
Screen Lines radio buttons 

THNST 143 
screens See also displays 

backgroimd, customizing 142 

color 
using 133 

colors, customizing 140-142 

dual 133 

EGA/VGA 124 

LCD 148 

lines per, setting 143 

monochrome 
using 133 

problems with 
snow 143 

repainting 143 

swapping 133, 142, 144 
problems with 162 

two 77 

updating 144 
scroll bars 66 
searches 

for text 80 

in list boxes 129 

repeat 81 

wildcards 80 
separate clock 

timer data and 83 
Separate option 

Area Options dialog box 103 
serial links, remote 147 
shortcuts See hot keys 
Sieve of Eratosthenes 28 
Size/Move command 127 
snow 143 
Sort command 89, 94 

Areas window 104 
Sort option 

Display Options dialog box 101 
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sorts 

bubble vs. quicksort 58 
source code See files, source; programs 
stack 
call 

size 84 
Stack command 84 
Start Time option 101 
starting Turbo Profiler 
on remote systems 

problems with 147 
startup information 3 
statements 
execution 

verifying 49 
return See return statements 
statistics 

accumulation 

disabling 115 
accuracy 53 
areas 102 
automatic collection 

turning on and off 1 14 
collecting 56 
collection 11,43,45 

automatic 77 

disabling 43, 83 

enabling 83 

normal 83 

program speed and 47 

type to collect 48 
collection options 103 
current 

removing 89 
current area 56 
current routine 106 
default 43 
displaying 12 

filtering display 47 
erasing 91, 117 
file activity 99 

graph view 101 

time in seconds 101 
files 

writing to, problems with 171 
filtering 46, 49, 56, 89 

temporary 90 



how taken 37 
interrupts See interrupts 
limiting 46 
overlays 95 

demonstration 95 
partial 45 
printing 16,119 
problems with 171 
program execution speed and 52 
removing 88 
restoring 118 
saving 17, 117 
sorting 88, 89 
start and stop points 

maximimi 45 
time 
average 88 
filters and 89 
longest 88 
types of 45 
viewing 78, 87, 88 
choices 88 
number of passes 88 
time 55 

with source code 18 
Statistics command 119 
Statistics menu 111 
status line 68 
Stop option 

Areas Options dialog box 103 
Files window 100 
Stop Recording command 123 
strings 
character 
searching for 167 
structure analysis 
statistics for 48 
Subroutines command 97 
support 

technical 5 
switch statements See case and switch 

statements 
s5niibol names, problems with 169 
symbol tables 175 
invalid 175 
loading 
problems with 173 
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memory allocation 146 
symbols 

accessing 168 

disassembled 107 

problems with 176 
System menu See = (System) menu 



Tab Size input box 124 

TFINST 144 
tabs 

setting 124 
tabs, setting 144 

problems with 176 
Tandy lOOOA and NMI 146 
TD286 protected-mode profiler 

instructions 162 
TDH386.SYS 160, 162 
TDREMOTE 
running 
problems with 1 75 
TDRF (remote ffle transfer utility) 152 
technical support 5 
terminology 5 
text 

boxes 70 

Get Info 76 
editors 145 

problems with 170 
entering in dialog boxes 70 
searching for 80 
problems with 176 
TF386 virtual profiler 159-164 
command-line options 161 

syntax 162 
error messages 163-164 
installation 
device driver 160 
system requirements 159 
problems with 162 
starting 160 
problems with 163 
.TFA files 

areas and 40 
TFCONFIG.TF 19 
TFH386.SYS 

error messages 164 



TFINST 139-150 

command-line options vs. 148-149 

exiting 150 

main menu 140 

options, saving 149 
TFREMOTE (remote profiling utility) 151 

customizing 155 

error messages 156-158 

installing 152 

options See command line, options 

starting 153 
.TFSfile 

saving to 111 
.TFS files 

creating 17, 117 
This Line command 

Add Areas 81 

Remove Areas 82 
This Module command 84 
This Routine command 84 
time 

propagation 104 
time-and-counts profile listing 14 
Time option 88, 98 
timer 

combined clock 46, 83 

data 
grouping 46 

inaccurate results and 37 

separate clock 83 

setting 113 

sound routines and 37 
Timer command 83 
Timing option 

Area Options dialog box 103 
title bars 66 
TPROF.EXE 149 
TSR programs 

display swapping and 144 
Turbo C 

identifiers 91 
Turbo language products 

Turbo Profiler and 42 
Turbo Profiler 

leaving 77, 78 
Turbo Profiler Statistics file See .TFS files 
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tutorial 7-28 

numeric coprocessors and 9 

u 

underbars See underscores 
underscores 

identifiers and 57 

Turbo C identifiers and 91 
Undo Close command 128 
Use Expanded Memory check box (TFINST) 

146 
User Screen 

swapping 124 
User screen 

display buffer 143 

updating 144 
User Screen command 128 
User Screen Updating radio buttons (TFINST) 

144 
User Screen window 

remote profiling and 152 
utilities 

TDRF 152 

TFREMOTE See TFREMOTE (remote 

profiling utility) 

V 

-V option (video hardware) 136 

version number information 73 

VGA See Video Graphics Array Adapter 

video adapters 147, See also Enhanced Graphics 

Adapter; graphics drivers; Video Graphics 

Array Adapter 

display pages 144 

options 136 
Video Graphics Array Adapter (VGA) See also 

graphics; video adapters 

50-line mode 
disabling 136 

line display 143 

screen 124 
View Source command 109 

w 

-w option (save option settings) 154, 155 



TF386 virtual profiler 161, 163 
warning beeps, enabling 145 
When Full command 100 
Width of Names input box 124 
wildcards 
DOS 75, 177 
in searches 80 
Window menu 127 
windows 
active 67 

defined 65 

shrinking 127 

zooming 727 
Areas 707 

Callers option and 92 
Callers 91 
closing 66, 67, 128 
customizing 740 
Disassembly (CPU) 706 
Execution Profile 86 

Module window and 87 
FUes 98, 99 
Help 129 
Interrupts 96 
linking 18 
Module 

Execution Profile and 87 
moving 67, 127 
next 727 
next pane 727 
open 

list of 729 
opening 67, 128 
Overlays 95 

demonstration 95 
printing contents oi 119 
problems with 773 
profile report 55, 56 
program report 55 
program source 55 
report See report windows 
resizing 18, 67 
restoring 73 
Routine 704 
saving configuration 19 
scrolling 66 
sizing 727 
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User screen 128 

zooming 1 1, 66, 67, 127 
Windows command (TFINST) 140 
WordStar-style cursor-movement commands 

146 
Wrap option 100 

X 

XMS standard 161 



-y option (set overlay area size) 136 
Yes option 

Disassembly (CPU) window 109 



Zoom command 1 1, 127 
zoom icon 66, 67 
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